Claude Code Spec Workflow

When performing a bug analysis, follow these steps:

1. Prerequisites: Ensure report.md exists and is complete, then load the bug report and steering documents.
2. Investigation:
   • Code Investigation: Search the codebase, map data flow, and identify failure points.
   • Root Cause Analysis: Determine the underlying cause and why existing tests failed.
   • Solution Planning: Design a fix strategy and plan the testing approach.
3. Documentation: Create an analysis document using the exact structure defined in .claude/templates/bug-analysis-template.md.
4. Approval: Present the analysis and wait for explicit approval (e.g., "yes", "approved") before proceeding to the next phase.

When breaking down a design into tasks, follow these atomicity requirements to ensure tasks are agent-friendly and executable:

• File Scope: Each task should touch a maximum of 1-3 related files.
• Time Boxing: Tasks should be completable in 15-30 minutes.
• Single Purpose: Each task must have one testable outcome.
• Specific Files: Tasks must specify exact files to create or modify.
• Format: Use a checkbox format with a numbered hierarchy.

Examples of Good vs Bad Tasks:

• BAD: Implement authentication system
• GOOD: Create User model in models/user.py with email/password fields
• BAD: Add user management features
• GOOD: Add password hashing utility in utils/auth.py using bcrypt

When a task is finished, you must use the get-tasks command with the --mode complete flag to update the task status. This is a critical step in the workflow protocol.

Protocol:

1. Run the completion command.
2. State clearly: "Task X has been marked as complete".
3. Stop execution: Do not automatically proceed to the next task; wait for user instruction.

claude-code-spec-workflow get-tasks {feature-name} {task-id} --mode complete

For fixing bugs in existing code, follow the dedicated bug workflow sequence within Claude Code.

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

To ensure effective project steering, follow these guidelines:

• Persistence: Remember that these documents are persistent and will be referenced in all future spec commands.
• Focus: Keep each document focused on its specific domain (product.md, tech.md, or structure.md).
• Evolution: Update steering documents regularly as the project evolves.
• Security: Never include sensitive data such as passwords, API keys, or credentials in these documents.

Steering documents provide persistent project context (vision, tech stack, and organization) that guides all subsequent spec development and ensures consistent code generation.

Run /spec-steering-setup to create the following files in .claude/steering/:

• product.md: Product vision, target users, and objectives.
• tech.md: Tech stack, frameworks, and technical constraints.
• structure.md: File organization, naming conventions, and import patterns.

Follow these steps to complete the verification phase:

1. Original Bug Testing: Reproduce the steps from report.md and verify the bug no longer occurs, including edge cases from analysis.md.
2. Regression Testing: Test related functionality and integration points to ensure no new bugs were introduced. Run automated tests if available.
3. Code Quality Verification: Review changes for adherence to project standards, appropriate error handling, and adequate test coverage.
4. Create Verification Document: Use the pre-loaded bug verification template to document all test results. Do not omit any sections.
5. Final Approval: Present results and ask: "The bug fix has been verified successfully. Is this bug resolved?" to get final confirmation.

To use the workflow, install the package globally and then run the setup command within your target project directory. This creates the .claude/ directory structure containing commands, steering documents, templates, specs, bugs, and agents.

Prerequisites:

• Node.js 16.0.0 or higher
• Claude Code installed and configured (npm install -g @anthropic-ai/claude-code)

Installation steps:

1. Install globally: npm i -g @pimzino/claude-code-spec-workflow
2. Run setup in your project: claude-code-spec-workflow

Before starting the verification process, you must load the hierarchical context to ensure the correct verification structure and templates are available.

Run the following command to load the bug templates:

claude-code-spec-workflow get-template-context bug

Additionally, you should directly read the following bug documents to understand the context:

• .claude/bugs/{bug-name}/report.md
• .claude/bugs/{bug-name}/analysis.md

Before starting the specification phases, you must set up the directory structure and load the necessary context (steering documents and templates) to ensure the AI assistant has the correct project standards and structural guidance.

1. Create Directory Structure: Create .claude/specs/{feature-name}/ and initialize empty requirements.md, design.md, and tasks.md files.
2. Load Context: Use the following commands to load project standards and templates once at the beginning of the process.

# Load steering documents (if available)
claude-code-spec-workflow get-steering-context

# Load specification templates for structure guidance
claude-code-spec-workflow get-template-context spec

When running the bug creation process, the workflow initializes a dedicated directory for the bug to maintain organized documentation:

1. Create directory: .claude/bugs/{bug-name}/
2. Initialize files:
   • report.md
   • analysis.md
   • verification.md

Note: Always use kebab-case for the {bug-name}.