@pimzino/claude-code-spec-workflow
Advanced tools
Automated workflows for Claude Code. Includes spec-driven development (Requirements → Design → Tasks → Implementation) with intelligent task execution, optional steering documents and streamlined bug fix workflow (Report → Analyze → Fix → Verify). We have
⚠️ 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.
npm i -g @pimzino/claude-code-spec-workflow
claude-code-spec-workflow
Complete automation in one command:
/spec-create feature-name "Description"
What happens:
Execute tasks:
# Manual control
/spec-execute 1 feature-name
/feature-name-task-1 # Auto-generated
/bug-create issue-name "Description" # Document the bug
/bug-analyze # Find root cause
/bug-fix # Implement solution
/bug-verify # Confirm resolution
/spec-steering-setup # Creates product.md, tech.md, structure.md
| 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 |
| 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 |
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.
get-steering-context, get-spec-context, and get-template-contextget-content when optimization unavailablenpx -p @pimzino/claude-code-spec-workflow claude-spec-dashboard
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:
# 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
# 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 provide persistent project context that guides all spec development:
product.md)tech.md)structure.md)Run /spec-steering-setup to create these documents. Claude will analyze your project and help you define these standards.
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)
The package includes a built-in test command:
# Test setup in temporary directory
npx @pimzino/claude-code-spec-workflow test
❓ 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 --version
cd 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
done
The dashboard frontend is fully implemented in TypeScript for enhanced type safety and developer experience:
// 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 };
# 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
// 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') };
}
Contributions are welcome! Please see our Contributing Guide.
MIT License - see LICENSE for details.
See CHANGELOG.md for version history.
| 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 |
# Install globally (recommended)
npm install -g @pimzino/claude-code-spec-workflow
# Verify installation
claude-code-spec-workflow --version
# Basic setup
claude-code-spec-workflow
# Advanced options
claude-code-spec-workflow --project /path --force --yes
During setup you choose:
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-'.
# 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-create login-timeout "Users logged out too quickly"
/bug-analyze
/bug-fix
/bug-verify
The package includes optimized commands for efficient document loading across all document types:
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)
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)
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
get-content for edge casesget-content when neededThe system implements a sophisticated hierarchical context management strategy for maximum efficiency:
Main Agents (Commands like /spec-execute, /spec-create):
Sub-Agents (Agents like spec-task-executor):
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.
❓ "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
MIT License - LICENSE
Made with ❤️ by Pimzino
Special Thanks:
Powered by: Claude Code • Mermaid • TypeScript
[1.5.9] - 2025-09-07
FAQs
Automated workflows for Claude Code. Includes spec-driven development (Requirements → Design → Tasks → Implementation) with intelligent task execution, optional steering documents and streamlined bug fix workflow (Report → Analyze → Fix → Verify). We have
The npm package @pimzino/claude-code-spec-workflow receives a total of 1,549 weekly downloads. As such, @pimzino/claude-code-spec-workflow popularity was classified as popular.
We found that @pimzino/claude-code-spec-workflow demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.