specpulse 1.0.6__py3-none-any.whl → 1.1.0__py3-none-any.whl

specpulse/resources/commands/claude/sp-continue.md

@@ -0,0 +1,203 @@
+---
+name: sp-continue
+description: Switch context and continue work on a specific feature
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - TodoWrite
+---
+
+# /sp-continue Command
+
+Switch context to a specific feature and continue work from where you left off.
+
+## Usage
+```
+/sp-continue <feature-name|feature-id>
+```
+
+## Implementation
+
+When called with `/sp-continue $ARGUMENTS`, I will:
+
+1. **Parse arguments** to extract feature name or ID
+2. **Find feature directory** using context detection:
+   - Search for matching feature directory (specs/*, plans/*, tasks/*)
+   - Support partial matching (e.g., "auth" matches "001-user-authentication")
+   - Support ID matching (e.g., "001" matches "001-user-authentication")
+
+3. **Validate feature exists**:
+   - Check if feature directory has any files
+   - Verify feature structure is intact
+   - Report if feature not found
+
+4. **Update context** in `memory/context.md`:
+   ```yaml
+   # Feature Context
+   
+   ## Current Feature
+   - **ID**: 001
+   - **Name**: user-authentication
+   - **Branch**: 001-user-authentication
+   - **Status**: active
+   - **Created**: 2025-01-09
+   - **Last Updated**: 2025-01-09
+   - **Switched To**: 2025-01-09 (via /continue)
+   ```
+
+5. **Switch git branch** if in git repository:
+   - Checkout feature branch if it exists
+   - Report if branch doesn't exist
+   - Handle branch switching errors gracefully
+
+6. **Display feature status**:
+   - Show current progress percentage
+   - List next available actions
+   - Highlight any blockers or issues
+   - Show recent activity
+
+7. **Suggest next steps** based on feature state:
+   - If no spec files: `/spec <description>`
+   - If spec but no plan: `/plan`
+   - If plan but no tasks: `/task`
+   - If tasks exist: Show task completion status and suggest next task
+
+## Feature Detection Logic
+
+The command supports multiple ways to identify features:
+
+### By Name
+```
+/sp-continue user-authentication
+/sp-continue "user authentication"
+/sp-continue auth
+```
+
+### By ID
+```
+/sp-continue 001
+/sp-continue 002
+```
+
+### By Partial Match
+```
+/sp-continue user  # Matches any feature with "user" in name
+/sp-continue pay   # Matches "payment-processing"
+```
+
+## Context Switching
+
+When switching features, the system:
+
+1. **Saves previous context**:
+   - Stores previous feature state
+   - Notes switch reason and timestamp
+   - Preserves all progress tracking data
+
+2. **Loads new context**:
+   - Updates `memory/context.md` with new feature
+   - Loads feature metadata
+   - Calculates current progress
+
+3. **Environment setup**:
+   - Switches git branch if available
+   - Updates working directory context
+   - Prepares for continued development
+
+## Examples
+
+### Basic feature switch
+```
+User: /sp-continue user-authentication
+```
+
+I will:
+- Find feature: `001-user-authentication`
+- Update context: Switch from current feature to `001-user-authentication`
+- Switch git branch: `git checkout 001-user-authentication`
+- Display status:
+  ```
+  ## Switched to Feature: 001-user-authentication
+  
+  **Progress**: 65% complete
+  **Status**: Active
+  **Last Worked**: 2025-01-09
+  
+  ### Next Steps
+  - 16 tasks completed, 9 remaining
+  - 1 blocker: T015 (Database schema approval)
+  - Suggested action: /sp-status user-authentication for details
+  ```
+
+### Continue with ID
+```
+User: /sp-continue 002
+```
+
+I will:
+- Find feature: `002-payment-processing`
+- Switch context and display feature status
+
+### Feature not found
+```
+User: /sp-continue non-existent-feature
+```
+
+I will:
+- Search for matching features
+- Show available features:
+  ```
+  Feature "non-existent-feature" not found.
+  
+  Available features:
+  - 001-user-authentication (65%)
+  - 002-payment-processing (23%)
+  - 003-user-profile (45%)
+  
+  Use /sp-status to see all features.
+  ```
+
+## Integration Features
+
+- **Intelligent feature matching** with partial name and ID support
+- **Context preservation** when switching between features
+- **Git integration** with automatic branch switching
+- **Progress tracking** across feature switches
+- **Smart suggestions** for next actions based on feature state
+- **Error recovery** with helpful fallback options
+- **Cross-platform compatibility** for any development environment
+
+## Error Handling
+
+- Feature not found with suggestions
+- Git branch switching errors
+- Context file permission issues
+- Directory structure validation
+- Progress calculation errors
+- Working directory validation
+
+## Multi-Feature Workflow
+
+The `/continue` command enables efficient multi-feature development:
+
+```
+# Start new feature
+/sp-pulse new-feature
+/sp-spec "feature description"
+/sp-plan
+/sp-task
+
+# Switch to existing feature
+/sp-continue user-authentication
+
+# Check status and continue work
+/sp-status user-authentication
+# ... complete some tasks ...
+
+# Switch back to new feature
+/sp-continue new-feature
+```
+
+This enables developers to context-switch between multiple active features while maintaining progress tracking and development context.

specpulse/resources/commands/claude/{plan.md → sp-plan.md}

@@ -1,5 +1,5 @@
 ---
-name: plan
+name: sp-plan
 description: Generate or validate implementation plans using AI-optimized templates
 allowed_tools:
   - Read
@@ -9,55 +9,65 @@ allowed_tools:
   - TodoWrite
 ---
 
-# /plan Command
+# /sp-plan Command
 
 Generate implementation plans from specifications following SpecPulse methodology with constitutional compliance and AI-optimized templates.
 
 ## Usage
 ```
-/plan [action] [feature-directory]
+/sp-plan [action] [feature-directory]
 ```
 
 Actions: `generate`, `validate`, `optimize` (defaults to `generate`)
 
 ## Implementation
 
-When called with `/plan $ARGUMENTS`, I will:
+When called with `/sp-plan $ARGUMENTS`, I will:
 
-1. **Parse arguments** and determine action:
+1. **Detect current feature context**:
+   - Read `memory/context.md` for current feature metadata
+   - Use git branch name if available (e.g., `001-user-authentication`)
+   - Fall back to most recently created feature directory
+   - If no context found, ask user to specify feature or run `/sp-pulse` first
+
+2. **Parse arguments** and determine action:
    - If `validate`: Check plan against constitutional gates
    - If `optimize`: Improve existing plan complexity
    - Otherwise: Generate new plan
 
-2. **For `/plan generate` or `/plan`:**
-   a. **Find and validate specification** from current context or provided directory
+3. **For `/sp-plan generate` or `/sp-plan`:**
+   a. **Show existing spec files**: List all spec-XXX.md files in current feature directory
+   b. **Ask user to select**: Which spec file to base plan on
+   c. **Find and validate specification** from selected spec file
    
-   b. **Enhanced validation** using cross-platform script:
+   d. **Enhanced validation** using cross-platform script:
       ```bash
       # Cross-platform detection
       if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
-          powershell scripts/pulse-plan.ps1 "$FEATURE_DIR"
+          python scripts/sp-pulse-plan.py "$FEATURE_DIR"
       else
-          bash scripts/pulse-plan.sh "$FEATURE_DIR" || python scripts/pulse-plan.py "$FEATURE_DIR"
+          bash scripts/sp-pulse-plan.sh "$FEATURE_DIR" || python scripts/sp-pulse-plan.py "$FEATURE_DIR"
       fi
       ```
 
-   c. **Run Constitutional Phase Gates** (Article VII):
+   e. **Run Constitutional Phase Gates** (Article VII):
       - Simplicity Gate: ≤3 modules justification
       - Anti-Abstraction Gate: Direct framework usage
       - Test-First Gate: Tests before implementation
       - Integration-First Gate: Real services over mocks
       - Research Gate: Technology choices documented
 
-   d. **Generate AI-optimized plan** using template variables:
+   f. **Generate AI-optimized plan** using template variables:
       ```markdown
       # Implementation Plan: {{ feature_name }}
       ## Specification Reference
       - **Spec ID**: SPEC-{{ feature_id }}
+      - **Spec Version**: {{ spec_version }}
+      - **Plan Version**: {{ plan_version }}
       - **Generated**: {{ date }}
       ```
 
-   e. **Generate comprehensive sections**:
+   g. **Generate comprehensive sections**:
       - Technology stack with performance implications
       - Architecture overview with component relationships
       - Implementation phases with timeline estimates
@@ -67,37 +77,42 @@ When called with `/plan $ARGUMENTS`, I will:
       - Security considerations with compliance requirements
       - Deployment strategy with rollback plans
 
-   f. **Complexity tracking** (Article VII):
+   h. **Complexity tracking** (Article VII):
       - Document all complexity exceptions with justifications
       - Create mitigation strategies for each exception
       - Track optimization opportunities
 
-   g. **Write optimized plan** to `plans/XXX-feature/plan.md`
+   i. **Version management**: Check existing plan files and create next version (plan-001.md, plan-002.md, etc.)
+   j. **Write optimized plan** to `plans/XXX-feature/plan-XXX.md`
 
-3. **For `/plan validate`:**
-   - **Enhanced validation** using cross-platform script:
+4. **For `/sp-plan validate`:**
+   a. **Show existing plan files**: List all plan-XXX.md files in current feature directory
+   b. **Ask user to select**: Which plan file to validate
+   c. **Enhanced validation** using cross-platform script:
      ```bash
      # Cross-platform detection
      if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
-         powershell scripts/pulse-plan.ps1 "$FEATURE_DIR"
+         python scripts/sp-pulse-plan.py "$FEATURE_DIR"
      else
-         bash scripts/pulse-plan.sh "$FEATURE_DIR" || python scripts/pulse-plan.py "$FEATURE_DIR"
+         bash scripts/sp-pulse-plan.sh "$FEATURE_DIR" || python scripts/sp-pulse-plan.py "$FEATURE_DIR"
      fi
      ```
-   - Verify all constitutional gates are addressed
-   - Check complexity exceptions have proper justifications
-   - Validate test-first approach is documented
-   - Ensure integration strategy uses real services
-   - Report detailed validation results
-
-4. **For `/plan optimize`:**
-   - **Read existing plan** and analyze complexity
-   - **Identify optimization opportunities**:
-     - Module consolidation opportunities
-     - Abstraction layer removal candidates
-     - Simplification strategies
-   - **Generate optimization recommendations**
-   - **Update plan** with reduced complexity
+   d. Verify all constitutional gates are addressed
+   e. Check complexity exceptions have proper justifications
+   f. Validate test-first approach is documented
+   g. Ensure integration strategy uses real services
+   h. Report detailed validation results
+
+5. **For `/sp-plan optimize`:**
+   a. **Show existing plan files**: List all plan-XXX.md files in current feature directory
+   b. **Ask user to select**: Which plan file to optimize
+   c. **Read existing plan** from detected context and analyze complexity
+   d. **Identify optimization opportunities**:
+      - Module consolidation opportunities
+      - Abstraction layer removal candidates
+      - Simplification strategies
+   e. **Generate optimization recommendations**
+   f. **Create new version**: Write optimized plan as next version (plan-XXX.md)
 
 ## Constitutional Phase Gates (Phase -1)
 
@@ -137,17 +152,17 @@ When called with `/plan $ARGUMENTS`, I will:
 
 ### Generate plan with validation
 ```
-User: /plan generate
+User: /sp-plan generate
 ```
 I will:
-- Run: `bash scripts/pulse-plan.sh "$FEATURE_DIR"`
+- Run: `bash scripts/sp-pulse-plan.sh "$FEATURE_DIR"`
 - Validate: Constitutional gates compliance
 - Create: AI-optimized plan with template variables
 - Output: `CONSTITUTIONAL_GATES_STATUS=PENDING`
 
 ### Validate existing plan
 ```
-User: /plan validate
+User: /sp-plan validate
 ```
 I will run comprehensive validation:
 ```
@@ -159,7 +174,7 @@ STATUS=validation_complete
 
 ### Optimize plan complexity
 ```
-User: /plan optimize
+User: /sp-plan optimize
 ```
 I will analyze and recommend complexity reductions.
 
@@ -167,7 +182,7 @@ I will analyze and recommend complexity reductions.
 
 - **AI-optimized templates** with Jinja2-style variables
 - **Cross-platform script execution** with automatic detection
-- **Enhanced script integration** for Bash, PowerShell, and Python
+- **Enhanced script integration** for Bash and Python
 - **Constitutional compliance tracking** with gate status
 - **Complexity exception management** with justifications
 - **Performance and security considerations** integrated

specpulse/resources/commands/claude/sp-pulse.md

@@ -0,0 +1,142 @@
+---
+name: sp-pulse
+description: Initialize a new feature with SpecPulse framework
+allowed_tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - TodoWrite
+---
+
+# /sp-pulse Command
+
+Initialize a new feature following SpecPulse methodology with constitutional compliance.
+
+## Usage
+```
+/sp-pulse <feature-name> [feature-id]
+```
+
+## Implementation
+
+When called with `/sp-pulse $ARGUMENTS`, I will:
+
+1. **Validate arguments** and extract feature name + optional ID
+2. **Run initialization script** with cross-platform detection:
+   - **Linux/macOS**: `bash scripts/sp-pulse-init.sh "$FEATURE_NAME" "$OPTIONAL_ID"`
+   - **Python Fallback**: `python scripts/sp-pulse-init.py "$FEATURE_NAME" "$OPTIONAL_ID"`
+3. **Create complete feature structure**:
+   - Generate feature ID (001, 002, etc.) or use provided ID
+   - Create sanitized branch name: `ID-feature-name`
+   - Create directories: `specs/ID-feature-name/`, `plans/ID-feature-name/`, `tasks/ID-feature-name/`
+   - Copy AI-optimized templates to feature directories
+   - Update `memory/context.md` with current feature metadata
+   - Create and switch to git branch if in git repository
+
+4. **Suggest specification creation**:
+   - Provide user with 2-3 AI-generated specification suggestions
+   - Ask user to choose one or create custom specification
+   - Guide user to use `/sp-spec` command after making selection
+
+5. **Validate structure** and report comprehensive status
+
+## Constitutional Compliance
+
+**Article I: Simplicity**
+- [ ] Feature name is clear and specific
+- [ ] No unnecessary abstractions in initial structure
+- [ ] Single responsibility per feature
+
+**Article II: Anti-Abstraction**  
+- [ ] Direct template usage (no wrapper layers)
+- [ ] Minimal initial structure
+- [ ] Framework-ready files
+
+## Example
+```
+User: /sp-pulse user-authentication-oauth2
+```
+
+I will:
+- Run: `bash scripts/sp-pulse-init.sh "user-authentication-oauth2"`
+- Create: `specs/001-user-authentication-oauth2/` (empty, ready for spec)
+- Create: `plans/001-user-authentication-oauth2/` (empty, ready for plan)
+- Create: `tasks/001-user-authentication-oauth2/` (empty, ready for tasks)
+- Branch: `001-user-authentication-oauth2`
+- Suggest specification options:
+  1. "User authentication with OAuth2 providers and JWT tokens"
+  2. "Complete authentication system including registration, login, and profile management"
+  3. "OAuth2 integration with social login providers"
+- Ask: "Which specification would you like to use? (Choose 1-3 or provide your own)"
+- Guide: "After choosing, use `/sp-spec [your choice]` to create the specification"
+- Status: `STATUS=ready_for_spec, BRANCH_NAME=001-user-authentication-oauth2`
+
+## Error Handling
+
+Enhanced validation includes:
+- Feature name sanitization (alphanumeric, hyphens only)
+- Directory creation validation
+- Template existence verification
+- Git repository validation
+- Context file management
+
+## Manual Workflow
+
+The `/sp-pulse` command creates the feature structure and then guides you through manual steps:
+
+1. **Phase -1**: **MANUAL** - Use `/sp-spec` to create specification with AI assistance
+2. **Phase 0**: **MANUAL** - Use `/sp-plan` to generate implementation plan  
+3. **Phase 1**: **MANUAL** - Use `/sp-task` to create task breakdown
+4. **Implementation**: Begin development following constitutional principles
+
+## Context Detection
+
+The system automatically detects which feature you're working on:
+- Checks `memory/context.md` for current feature
+- Uses git branch name if available
+- Falls back to most recently created feature directory
+- You can also specify feature directory explicitly in commands
+
+## Integration Features
+
+- **Automatic context tracking** in `memory/context.md`
+- **Enhanced error reporting** with specific failure reasons
+- **Git integration** with branch management
+- **Template validation** before copying
+- **Todo list creation** for progress tracking
+- **Cross-platform script execution** with automatic detection
+- **Multiple language support**: Bash, PowerShell, Python
+- **Platform-agnostic operation** for any development environment
+
+## Feature Progress Tracking
+
+The system tracks progress across all features:
+
+### Active Features Overview
+```
+FEATURE_COUNT=3
+ACTIVE_FEATURE=001-user-authentication
+COMPLETED_FEATURES=1
+IN_PROGRESS_FEATURES=2
+```
+
+### Context Management
+- `memory/context.md` tracks current active feature
+- Progress percentages calculated from task completion
+- Feature status: active, completed, paused, blocked
+- Automatic context switching when working on different features
+
+### Multi-Feature Workflow
+```
+/sp-pulse feature-a → /sp-spec → /sp-plan → /sp-task → [work]
+/sp-pulse feature-b → /sp-spec → /sp-plan → /sp-task → [work]
+/sp-status feature-a → Check progress → /sp-continue feature-a
+```
+
+### Feature Switching
+When you have multiple features, the system helps you:
+- List all existing features with their status
+- Switch context between features
+- Continue work from where you left off
+- Track overall project progress across all features

specpulse/resources/commands/claude/{spec.md → sp-spec.md}

@@ -1,5 +1,5 @@
 ---
-name: spec
+name: sp-spec
 description: Create or manage feature specifications using AI-optimized templates
 allowed_tools:
   - Read
@@ -9,29 +9,35 @@ allowed_tools:
   - TodoWrite
 ---
 
-# /spec Command
+# /sp-spec Command
 
 Create, update, or validate feature specifications using SpecPulse methodology with AI-optimized templates.
 
 ## Usage
 ```
-/spec [action] [description|feature-name]
+/sp-spec [action] [description|feature-name]
 ```
 
 Actions: `create`, `update`, `validate`, `clarify` (defaults to `create`)
 
 ## Implementation
 
-When called with `/spec $ARGUMENTS`, I will:
+When called with `/sp-spec $ARGUMENTS`, I will:
 
-1. **Parse arguments** to determine action:
+1. **Detect current feature context**:
+   - Read `memory/context.md` for current feature metadata
+   - Use git branch name if available (e.g., `001-user-authentication`)
+   - Fall back to most recently created feature directory
+   - If no context found, ask user to specify feature or run `/sp-pulse` first
+
+2. **Parse arguments** to determine action:
    - If starts with `create`: Generate new specification
    - If starts with `update`: Modify existing specification
    - If starts with `validate`: Check specification completeness
    - If starts with `clarify`: Address [NEEDS CLARIFICATION] markers
    - If no action specified: Default to `create` with full arguments as description
 
-2. **For `/spec create [description]` or `/spec [description]`:**
+3. **For `/sp-spec create [description]` or `/sp-spec [description]`:**
    - Read AI-optimized template from `templates/spec.md`
    - Parse the description to identify:
      - Functional requirements (Must/Should/Could/Won't have)
@@ -43,32 +49,37 @@ When called with `/spec $ARGUMENTS`, I will:
      # Specification: {{ feature_name }}
      ## Metadata
      - **ID**: SPEC-{{ feature_id }}
+     - **Version**: {{ version }}
      - **Created**: {{ date }}
      ```
    - Mark any uncertainties with `[NEEDS CLARIFICATION: specific question]`
-   - Find current feature directory from context or create new
-   - Write specification to `specs/ID-feature-name/spec.md`
+   - Use detected feature context to determine target directory
+   - **Version management**: Check existing spec files and create next version (spec-001.md, spec-002.md, etc.)
+   - Write specification to `specs/ID-feature-name/spec-XXX.md`
    - Run enhanced validation with cross-platform detection:
-     - **Windows**: `powershell scripts/pulse-spec.ps1 "$FEATURE_DIR"`
-     - **Linux/macOS**: `bash scripts/pulse-spec.sh "$FEATURE_DIR"`
-     - **Python Fallback**: `python scripts/pulse-spec.py "$FEATURE_DIR"`
+     - **Linux/macOS**: `bash scripts/sp-pulse-spec.sh "$FEATURE_DIR"`
+     - **Python Fallback**: `python scripts/sp-pulse-spec.py "$FEATURE_DIR"`
 
-3. **For `/spec update`:**
-   - Read existing specification from current context
+4. **For `/sp-spec update`:**
+   - **Show existing spec files**: List all spec-XXX.md files in current feature directory
+   - **Ask user to select**: Which spec file to update
+   - Read selected specification file
    - Parse update requests and identify sections to modify
    - Update content while preserving AI-friendly template structure
    - Remove resolved `[NEEDS CLARIFICATION]` markers
    - Run validation to ensure completeness
 
-4. **For `/spec validate`:**
-   - Read current specification
+5. **For `/sp-spec validate`:**
+   - **Show existing spec files**: List all spec-XXX.md files in current feature directory
+   - **Ask user to select**: Which spec file to validate
+   - Read selected specification file from detected context
    - Check all required sections using enhanced validation:
      ```bash
      # Cross-platform detection
      if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
-         powershell scripts/pulse-spec.ps1 "$FEATURE_DIR"
+         python scripts/sp-pulse-spec.py "$FEATURE_DIR"
      else
-         bash scripts/pulse-spec.sh "$FEATURE_DIR" || python scripts/pulse-spec.py "$FEATURE_DIR"
+         bash scripts/sp-pulse-spec.sh "$FEATURE_DIR" || python scripts/sp-pulse-spec.py "$FEATURE_DIR"
      fi
      ```
    - Count `[NEEDS CLARIFICATION]` markers
@@ -76,7 +87,9 @@ When called with `/spec $ARGUMENTS`, I will:
    - Check constitutional compliance indicators
    - Report detailed validation results
 
-5. **For `/spec clarify`:**
+6. **For `/sp-spec clarify`:**
+   - **Show existing spec files**: List all spec-XXX.md files in current feature directory
+   - **Ask user to select**: Which spec file to clarify
    - Find all `[NEEDS CLARIFICATION]` markers
    - Address each uncertainty with user input
    - Update specification with resolved information
@@ -87,7 +100,7 @@ When called with `/spec $ARGUMENTS`, I will:
 
 ### Creating a new specification
 ```
-User: /spec create user authentication system with OAuth2 and JWT tokens
+User: /sp-spec create user authentication system with OAuth2 and JWT tokens
 ```
 I will create a comprehensive specification using AI-optimized templates with:
 - Jinja2-style variables for AI processing
@@ -97,13 +110,13 @@ I will create a comprehensive specification using AI-optimized templates with:
 
 ### Updating existing specification
 ```
-User: /spec update add password complexity requirements
+User: /sp-spec update add password complexity requirements
 ```
 I will read the current spec, update password requirements, and validate changes.
 
 ### Validating specification
 ```
-User: /spec validate
+User: /sp-spec validate
 ```
 I will run enhanced validation with detailed reporting:
 ```
@@ -115,7 +128,7 @@ STATUS=validation_complete
 
 ### Addressing clarifications
 ```
-User: /spec clarify
+User: /sp-spec clarify
 ```
 I will systematically address all [NEEDS CLARIFICATION] markers.
 
@@ -152,7 +165,7 @@ The AI-optimized specification template includes:
 ## Integration Features
 
 - **Cross-platform script execution** with automatic detection
-- **Enhanced script integration** with Bash, PowerShell, and Python support
+- **Enhanced script integration** with Bash and Python support
 - **Template variable processing** for AI optimization
 - **Automated validation** with detailed reporting
 - **Context-aware operation** using memory/context.md