specpulse 1.0.6__py3-none-any.whl → 1.2.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/sp-decompose.md

@@ -0,0 +1,227 @@
+---
+name: sp-decompose
+description: Decompose large specifications into microservices, APIs, and smaller components
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - TodoWrite
+---
+
+# /sp-decompose Command
+
+Decompose large specifications into smaller, manageable components with microservice boundaries, API contracts, and interface specifications.
+
+## Usage
+```
+/sp-decompose [spec-id] [options]
+```
+
+Options: `--microservices`, `--apis`, `--interfaces`, `--all` (defaults to `--all`)
+
+## Implementation
+
+When called with `/sp-decompose $ARGUMENTS`, I will:
+
+1. **Parse specification to decompose**:
+   - If spec-id provided (e.g., `001` or `001-authentication`), use that specification
+   - Otherwise, detect current feature from `memory/context.md` or git branch
+   - Read the target specification file from `specs/XXX-feature/spec-YYY.md`
+   - Analyze complexity and identify decomposition opportunities
+
+2. **Analyze decomposition strategy**:
+   - **Domain Analysis**: Identify bounded contexts and aggregate roots
+   - **Responsibility Mapping**: Group related functionalities
+   - **Data Flow Analysis**: Understand data dependencies
+   - **Integration Points**: Identify communication needs between components
+   - **Complexity Assessment**: Measure cognitive load and cyclomatic complexity
+
+3. **Generate microservice boundaries**:
+   - Apply Domain-Driven Design (DDD) principles
+   - Create service definitions with clear responsibilities:
+     ```yaml
+     service: user-authentication
+     responsibility: Handle user identity and access control
+     bounded_context: Identity Management
+     capabilities:
+       - User registration
+       - Authentication (OAuth2, JWT)
+       - Session management
+       - Password reset
+     data_ownership:
+       - users table
+       - sessions table
+       - tokens table
+     ```
+   - Define inter-service communication patterns
+   - Specify data consistency requirements
+
+4. **Create API contracts**:
+   - Generate OpenAPI 3.0 specifications for each service
+   - Define RESTful endpoints with clear semantics:
+     ```yaml
+     /api/v1/users:
+       post:
+         summary: Create new user
+         requestBody:
+           $ref: '#/components/schemas/UserCreateRequest'
+         responses:
+           201:
+             $ref: '#/components/schemas/UserResponse'
+     ```
+   - Specify request/response schemas
+   - Include authentication and authorization requirements
+   - Define rate limiting and caching strategies
+
+5. **Design interface specifications**:
+   - Create abstract interfaces for each component:
+     ```typescript
+     interface IAuthenticationService {
+       authenticate(credentials: Credentials): Promise<AuthToken>
+       validateToken(token: string): Promise<TokenValidation>
+       refreshToken(refreshToken: string): Promise<AuthToken>
+       revokeToken(token: string): Promise<void>
+     }
+     ```
+   - Define data transfer objects (DTOs)
+   - Specify event contracts for event-driven communication
+   - Create adapter patterns for external integrations
+
+6. **Generate decomposition artifacts using templates**:
+   - Read templates from `templates/decomposition/`
+   - Use template variables for AI processing
+   - Create structured output in `specs/XXX-feature/decomposition/`:
+     - **`microservices.md`**: From template with service boundaries
+     - **`api-contracts/`**: From OpenAPI template
+     - **`interfaces/`**: From interface template
+     - **`integration-map.md`**: Service communication
+   - Update `memory/context.md` with decomposition status
+
+7. **Validate decomposition**:
+   - Check for circular dependencies
+   - Verify data consistency boundaries
+   - Ensure single responsibility principle
+   - Validate against constitutional principles:
+     - Simplicity (≤3 modules per service)
+     - Clear boundaries
+     - Testability
+
+8. **Update workflow context**:
+   - Add decomposition results to `memory/context.md`
+   - Create feature-specific plan template with services
+   - Prepare for `/sp-plan generate` with service context
+   - Enable `/sp-task breakdown` per service
+   - Run validation: `python scripts/sp-pulse-decompose.py validate`
+
+## Examples
+
+### Basic decomposition
+```
+User: /sp-decompose 001
+```
+I will analyze spec 001 and create a complete decomposition with microservices, APIs, and interfaces.
+
+### Microservices only
+```
+User: /sp-decompose 002-ecommerce --microservices
+```
+I will focus on identifying microservice boundaries for the e-commerce specification.
+
+### API contracts focus
+```
+User: /sp-decompose --apis
+```
+I will generate detailed API contracts for the current feature specification.
+
+## Decomposition Principles
+
+### Domain-Driven Design
+- Bounded contexts define service boundaries
+- Aggregates determine data ownership
+- Ubiquitous language for clear communication
+
+### SOLID Principles
+- **S**ingle Responsibility: Each service has one reason to change
+- **O**pen/Closed: Services extensible without modification
+- **L**iskov Substitution: Interfaces are substitutable
+- **I**nterface Segregation: Focused, specific interfaces
+- **D**ependency Inversion: Depend on abstractions
+
+### Communication Patterns
+- **Synchronous**: REST APIs for request-response
+- **Asynchronous**: Events for decoupled communication
+- **Hybrid**: Command Query Responsibility Segregation (CQRS)
+
+## Output Structure
+
+```
+specs/001-authentication/decomposition/
+├── microservices.md          # Service definitions
+├── api-contracts/
+│   ├── auth-service.yaml     # OpenAPI spec
+│   ├── user-service.yaml     # OpenAPI spec
+│   └── session-service.yaml  # OpenAPI spec
+├── interfaces/
+│   ├── IAuthService.ts       # TypeScript interface
+│   ├── IUserRepository.ts    # Repository pattern
+│   └── IEventBus.ts         # Event bus interface
+├── data-models/
+│   ├── user.schema.json     # JSON Schema
+│   ├── session.proto        # Protocol Buffers
+│   └── events.avsc          # Avro schema
+├── integration-map.md        # Service communication
+└── migration-plan.md         # Decomposition strategy
+```
+
+## Constitutional Compliance
+
+**Article I: Simplicity**
+- Each service limited to 3 core modules
+- Clear, focused responsibilities
+- Minimal inter-service dependencies
+
+**Article V: Single Responsibility**
+- Services own their data
+- Clear aggregate boundaries
+- Independent deployment capability
+
+**Article VIII: Framework Selection**
+- Choose appropriate tech stack per service
+- Leverage existing libraries
+- Standardize communication protocols
+
+## Integration with SpecPulse Workflow
+
+1. **After `/sp-spec create`**: 
+   - AI analyzes spec complexity
+   - Suggests decomposition if >3 modules detected
+   - User confirms with `/sp-decompose`
+
+2. **During decomposition**:
+   - AI reads spec from `specs/XXX-feature/spec-YYY.md`
+   - Applies DDD analysis using spec content
+   - Generates artifacts using templates
+   - Updates memory/context.md
+
+3. **Before `/sp-plan generate`**: 
+   - Plan command detects decomposition
+   - Uses service boundaries for architecture
+   - Creates service-specific phases
+
+4. **During `/sp-task breakdown`**: 
+   - Tasks created per service
+   - Inter-service dependencies mapped
+   - Integration tasks generated
+
+5. **With `/sp-validate`**: 
+   - Validates service boundaries
+   - Checks circular dependencies
+   - Ensures constitutional compliance
+
+## Error Handling
+
+- Specification not found: Guide user to create spec first
+- Circular dependencies detected: Suggest refactoring
+- Too many services (>7): Recommend consolidation
+- Missing bounded contexts: Apply DDD analysis

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

@@ -0,0 +1,220 @@
+---
+name: sp-plan
+description: Generate or validate implementation plans using AI-optimized templates
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - TodoWrite
+---
+
+# /sp-plan Command
+
+Generate implementation plans from specifications following SpecPulse methodology with constitutional compliance and AI-optimized templates.
+
+## Usage
+```
+/sp-plan [action] [feature-directory]
+```
+
+Actions: `generate`, `validate`, `optimize` (defaults to `generate`)
+
+## Implementation
+
+When called with `/sp-plan $ARGUMENTS`, I will:
+
+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
+
+3. **For `/sp-plan generate` or `/sp-plan`:**
+   a. **Check for decomposition**: Look for `specs/XXX-feature/decomposition/` directory
+   b. **If decomposed**:
+      - Read decomposition artifacts (microservices.md, api-contracts/, interfaces/)
+      - Generate separate plans for each service
+      - Create integration plan for service coordination
+      - Structure: `plans/XXX-feature/service-A-plan.md`, `integration-plan.md`
+   c. **If not decomposed**:
+      - Show existing spec files and ask user to select
+      - Generate single monolithic plan
+   d. **Find and validate specification** from selected spec file
+   
+   d. **Enhanced validation** using cross-platform script:
+      ```bash
+      # Cross-platform detection
+      if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+          python scripts/sp-pulse-plan.py "$FEATURE_DIR"
+      else
+          bash scripts/sp-pulse-plan.sh "$FEATURE_DIR" || python scripts/sp-pulse-plan.py "$FEATURE_DIR"
+      fi
+      ```
+
+   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
+
+   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 }}
+      ```
+
+   g. **Generate comprehensive sections based on architecture**:
+      - **For decomposed specs**:
+        * Service-specific plans with bounded contexts
+        * Inter-service communication plans
+        * Data consistency strategies
+        * Service deployment order
+        * Integration testing approach
+      - **For monolithic specs**:
+        * Traditional layered architecture
+        * Module boundaries
+        * Single deployment strategy
+      - Common sections:
+        * Technology stack with performance implications
+        * Testing strategy with coverage targets
+        * Security considerations
+        * Deployment strategy with rollback plans
+
+   h. **Complexity tracking** (Article VII):
+      - Document all complexity exceptions with justifications
+      - Create mitigation strategies for each exception
+      - Track optimization opportunities
+
+   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`
+
+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
+         python scripts/sp-pulse-plan.py "$FEATURE_DIR"
+     else
+         bash scripts/sp-pulse-plan.sh "$FEATURE_DIR" || python scripts/sp-pulse-plan.py "$FEATURE_DIR"
+     fi
+     ```
+   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)
+
+**Must pass before implementation:**
+
+### Article VII: Simplicity Gate
+- [ ] Using ≤3 projects/modules for initial implementation
+- [ ] No future-proofing without documented need
+- [ ] Direct framework usage (no unnecessary wrappers)
+- [ ] Single model representation per concept
+
+### Article VII: Anti-Abstraction Gate  
+- [ ] Using framework features directly
+- [ ] No unnecessary abstraction layers
+- [ ] Clear, simple interfaces
+- [ ] Avoiding premature optimization
+
+### Article III: Test-First Gate
+- [ ] Test specifications written
+- [ ] Tests reviewed and approved
+- [ ] Tests confirmed to FAIL before implementation
+- [ ] TDD cycle planned (Red-Green-Refactor)
+
+### Article VIII: Integration-First Gate
+- [ ] Contract tests defined
+- [ ] Using real services over mocks
+- [ ] Production-like test environment planned
+- [ ] End-to-end test scenarios identified
+
+### Article VI: Research Gate
+- [ ] Library options researched
+- [ ] Performance implications documented
+- [ ] Security considerations analyzed
+- [ ] Trade-offs documented
+
+## Examples
+
+### Generate plan for decomposed spec
+```
+User: /sp-plan generate
+```
+Detecting decomposition in `specs/001-authentication/decomposition/`...
+I will create:
+- `plans/001-authentication/auth-service-plan.md`
+- `plans/001-authentication/user-service-plan.md`
+- `plans/001-authentication/integration-plan.md`
+
+### Generate plan for monolithic spec
+```
+User: /sp-plan generate
+```
+No decomposition found. Creating single plan:
+- `plans/001-authentication/plan-001.md`
+
+### Validate existing plan
+```
+User: /sp-plan validate
+```
+I will run comprehensive validation:
+```
+PLAN_FILE=plans/001-user-authentication/plan.md
+CONSTITUTIONAL_GATES_STATUS=COMPLETED
+MISSING_SECTIONS=0
+STATUS=validation_complete
+```
+
+### Optimize plan complexity
+```
+User: /sp-plan optimize
+```
+I will analyze and recommend complexity reductions.
+
+## Enhanced Features
+
+- **AI-optimized templates** with Jinja2-style variables
+- **Cross-platform script execution** with automatic detection
+- **Enhanced script integration** for Bash and Python
+- **Constitutional compliance tracking** with gate status
+- **Complexity exception management** with justifications
+- **Performance and security considerations** integrated
+- **Integration-first approach** with real service usage
+- **Detailed validation reporting** with specific recommendations
+- **Platform-agnostic operation** for any development environment
+
+## Error Handling
+
+- Specification existence validation
+- Constitutional gate compliance checking
+- Template structure validation
+- Directory structure verification
+- Feature context auto-discovery