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

specpulse/core/specpulse.py

@@ -17,8 +17,14 @@ class SpecPulse:
     def __init__(self, project_path: Optional[Path] = None):
         self.project_path = project_path or Path.cwd()
         self.config = self._load_config()
-        # Get resource directory path
-        self.resources_dir = Path(__file__).parent.parent / "resources"
+        # Get resource directory path using package data
+        import pkg_resources
+        try:
+            # Get the actual path to the resources directory in the installed package
+            self.resources_dir = Path(pkg_resources.resource_filename('specpulse', 'resources'))
+        except:
+            # Fallback to development path
+            self.resources_dir = Path(__file__).parent.parent / "resources"
     
     def _load_config(self) -> Dict:
         """Load project configuration"""

specpulse/resources/commands/claude/plan.md

@@ -1,73 +1,184 @@
 ---
 name: plan
-description: Generate or validate implementation plans
+description: Generate or validate implementation plans using AI-optimized templates
 allowed_tools:
   - Read
   - Write
   - Edit
   - Bash
+  - TodoWrite
 ---
 
 # /plan Command
 
-Generate implementation plans from specifications following SpecPulse methodology.
+Generate implementation plans from specifications following SpecPulse methodology with constitutional compliance and AI-optimized templates.
 
 ## Usage
 ```
-/plan [action]
+/plan [action] [feature-directory]
 ```
 
-Actions: `generate`, `validate` (defaults to `generate`)
+Actions: `generate`, `validate`, `optimize` (defaults to `generate`)
 
 ## Implementation
 
 When called with `/plan $ARGUMENTS`, I will:
 
-1. **Parse arguments** to determine action:
-   - If `$ARGUMENTS` is `validate`: Check plan against constitution
+1. **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. **Read current specification** from `specs/XXX-feature/spec.md`
+   a. **Find and validate specification** from current context or provided directory
    
-   b. **Run Phase Gates checks**:
-   - Constitutional compliance
-   - Simplicity check (≤3 modules)
-   - Test-first strategy defined
-   - Framework selection complete
-   - Research completed
-
-   c. **Generate plan sections**:
-   - Technology stack
-   - Architecture overview
-   - Implementation phases
-   - API contracts
-   - Data models
-   - Testing strategy
-
-   d. **Track complexity**:
-   - If >3 modules, document justification
-   - Create simplification roadmap
-
-   e. **Write plan** to `plans/XXX-feature/plan.md`
+   b. **Enhanced validation** using cross-platform script:
+      ```bash
+      # Cross-platform detection
+      if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+          powershell scripts/pulse-plan.ps1 "$FEATURE_DIR"
+      else
+          bash scripts/pulse-plan.sh "$FEATURE_DIR" || python scripts/pulse-plan.py "$FEATURE_DIR"
+      fi
+      ```
+
+   c. **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:
+      ```markdown
+      # Implementation Plan: {{ feature_name }}
+      ## Specification Reference
+      - **Spec ID**: SPEC-{{ feature_id }}
+      - **Generated**: {{ date }}
+      ```
+
+   e. **Generate comprehensive sections**:
+      - Technology stack with performance implications
+      - Architecture overview with component relationships
+      - Implementation phases with timeline estimates
+      - API contracts with authentication requirements
+      - Data models with validation rules
+      - Testing strategy with coverage targets
+      - Security considerations with compliance requirements
+      - Deployment strategy with rollback plans
+
+   f. **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`
 
 3. **For `/plan validate`:**
-   - Read existing plan from `plans/XXX-feature/plan.md`
-   - Verify Phase Gates compliance
-   - Check complexity tracking
-   - Ensure test-first approach
-   - Validate framework choices
-   - Report validation results
-
-## Phase Gates (Phase -1)
-Must pass before implementation:
-- ✅ Using ≤3 projects/modules
-- ✅ Tests defined before code
-- ✅ Using framework features directly
-- ✅ No premature abstractions
-- ✅ Research completed
-
-## Example
+   - **Enhanced validation** using cross-platform script:
+     ```bash
+     # Cross-platform detection
+     if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+         powershell scripts/pulse-plan.ps1 "$FEATURE_DIR"
+     else
+         bash scripts/pulse-plan.sh "$FEATURE_DIR" || python scripts/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
+
+## 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 with validation
+```
+User: /plan generate
+```
+I will:
+- Run: `bash scripts/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
+```
+I will run comprehensive validation:
+```
+PLAN_FILE=plans/001-user-authentication/plan.md
+CONSTITUTIONAL_GATES_STATUS=COMPLETED
+MISSING_SECTIONS=0
+STATUS=validation_complete
 ```
-/plan generate
-```
+
+### Optimize plan complexity
+```
+User: /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, PowerShell, 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

specpulse/resources/commands/claude/pulse.md

@@ -6,47 +6,86 @@ allowed_tools:
   - Read
   - Write
   - Edit
+  - TodoWrite
 ---
 
 # /pulse Command
 
-Initialize a new feature following SpecPulse methodology.
+Initialize a new feature following SpecPulse methodology with constitutional compliance.
 
 ## Usage
 ```
-/pulse <feature-name>
+/pulse <feature-name> [feature-id]
 ```
 
 ## Implementation
 
 When called with `/pulse $ARGUMENTS`, I will:
 
-1. **Extract feature name** from `$ARGUMENTS`
-2. **Run initialization script**: `bash scripts/pulse-init.sh "$ARGUMENTS"`
-3. **Create feature structure**:
-   - Generate feature ID (001, 002, etc.)
-   - Create directories: `specs/XXX-feature/`, `plans/XXX-feature/`, `tasks/XXX-feature/`
-   - Copy templates to feature directories
-   - Update `memory/context.md` with current feature
-   - Create git branch if in git repository
+1. **Validate arguments** and extract feature name + optional ID
+2. **Run initialization script** with cross-platform detection:
+   - **Windows**: `powershell scripts/pulse-init.ps1 "$FEATURE_NAME" "$OPTIONAL_ID"`
+   - **Linux/macOS**: `bash scripts/pulse-init.sh "$FEATURE_NAME" "$OPTIONAL_ID"`
+   - **Python Fallback**: `python scripts/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. **Report results** to user with created structure
+4. **Validate structure** and report comprehensive status
+5. **Create todo list** for tracking feature development progress
+
+## 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: /pulse user-authentication
+User: /pulse user-authentication-oauth2
 ```
 
 I will:
-- Run: `bash scripts/pulse-init.sh "user-authentication"`
-- Create: `specs/001-user-authentication/spec.md`
-- Create: `plans/001-user-authentication/plan.md`  
-- Create: `tasks/001-user-authentication/tasks.md`
-- Switch to branch: `001-user-authentication` (if git)
-- Report success and next steps
-
-## Next Steps
-After initialization:
-- Use `/spec` to create the specification
-- Use `/plan` to generate implementation plan
-- Use `/task` to break down into tasks
+- Run: `bash scripts/pulse-init.sh "user-authentication-oauth2"`
+- Create: `specs/001-user-authentication-oauth2/spec.md`
+- Create: `plans/001-user-authentication-oauth2/plan.md`  
+- Create: `tasks/001-user-authentication-oauth2/tasks.md`
+- Branch: `001-user-authentication-oauth2`
+- Status: `STATUS=initialized, 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
+
+## Next Steps (Constitutional Order)
+
+1. **Phase -1**: Use `/spec` to create specification with constitutional gates
+2. **Phase 0**: Use `/plan` to generate implementation plan with complexity tracking
+3. **Phase 1**: Use `/task` to break down into executable tasks
+4. **Implementation**: Begin development following constitutional principles
+
+## 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

specpulse/resources/commands/claude/spec.md

@@ -1,23 +1,24 @@
 ---
 name: spec
-description: Create or manage feature specifications
+description: Create or manage feature specifications using AI-optimized templates
 allowed_tools:
   - Read
   - Write
   - Edit
   - Bash
+  - TodoWrite
 ---
 
 # /spec Command
 
-Create, update, or validate feature specifications using SpecPulse methodology.
+Create, update, or validate feature specifications using SpecPulse methodology with AI-optimized templates.
 
 ## Usage
 ```
-/spec [action] [description]
+/spec [action] [description|feature-name]
 ```
 
-Actions: `create`, `update`, `validate` (defaults to `create`)
+Actions: `create`, `update`, `validate`, `clarify` (defaults to `create`)
 
 ## Implementation
 
@@ -27,55 +28,133 @@ When called with `/spec $ARGUMENTS`, I will:
    - 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]`:**
-   - Read template from `templates/spec.md`
+   - Read AI-optimized template from `templates/spec.md`
    - Parse the description to identify:
-     - Functional requirements (Must/Should/Could have)
-     - User stories and acceptance criteria
-     - Technical requirements
-   - Mark any uncertainties with `[NEEDS CLARIFICATION: detail]`
-   - Find current feature directory (latest in specs/)
-   - Write specification to `specs/XXX-feature/spec.md`
+     - Functional requirements (Must/Should/Could/Won't have)
+     - User stories with testable acceptance criteria
+     - Technical specifications and constraints
+     - Success metrics and out-of-scope items
+   - Generate specification using Jinja2-style template variables:
+     ```markdown
+     # Specification: {{ feature_name }}
+     ## Metadata
+     - **ID**: SPEC-{{ feature_id }}
+     - **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`
+   - 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"`
 
 3. **For `/spec update`:**
-   - Read existing specification
-   - Ask user for clarifications or changes
-   - Update content while preserving structure
+   - Read existing specification from current context
+   - 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`:**
-   - Check all required sections are filled
+   - Read current specification
+   - Check all required sections using enhanced validation:
+     ```bash
+     # Cross-platform detection
+     if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+         powershell scripts/pulse-spec.ps1 "$FEATURE_DIR"
+     else
+         bash scripts/pulse-spec.sh "$FEATURE_DIR" || python scripts/pulse-spec.py "$FEATURE_DIR"
+     fi
+     ```
    - Count `[NEEDS CLARIFICATION]` markers
-   - Verify acceptance criteria are testable
-   - Report validation results
+   - Verify acceptance criteria follow Given-When-Then format
+   - Check constitutional compliance indicators
+   - Report detailed validation results
+
+5. **For `/spec clarify`:**
+   - Find all `[NEEDS CLARIFICATION]` markers
+   - Address each uncertainty with user input
+   - Update specification with resolved information
+   - Remove clarification markers
+   - Re-run validation
 
 ## Examples
 
 ### Creating a new specification
 ```
-User: /spec user authentication with OAuth2 and email/password
+User: /spec create user authentication system with OAuth2 and JWT tokens
 ```
-I will create a comprehensive specification with all requirements.
+I will create a comprehensive specification using AI-optimized templates with:
+- Jinja2-style variables for AI processing
+- Constitutional compliance sections
+- Testable acceptance criteria
+- Automated validation
 
 ### Updating existing specification
 ```
-User: /spec update
+User: /spec update add password complexity requirements
 ```
-I will read the current spec and guide through updates.
+I will read the current spec, update password requirements, and validate changes.
 
 ### Validating specification
 ```
 User: /spec validate
 ```
-I will check completeness and report any issues.
-
-## Template Structure
-The specification follows this structure:
-- Project Overview
-- Functional Requirements (Must/Should/Could have)
-- User Stories with Acceptance Criteria  
-- Technical Specifications
-- Clarifications Needed
-- Validation Checklist
+I will run enhanced validation with detailed reporting:
+```
+SPEC_FILE=specs/001-user-authentication/spec.md
+CLARIFICATIONS_NEEDED=3
+MISSING_SECTIONS=0
+STATUS=validation_complete
+```
+
+### Addressing clarifications
+```
+User: /spec clarify
+```
+I will systematically address all [NEEDS CLARIFICATION] markers.
+
+## Enhanced Template Structure
+
+The AI-optimized specification template includes:
+- **Metadata**: Template variables for AI processing
+- **Constitutional Gates**: Pre-implementation validation
+- **Functional Requirements**: Structured Must/Should/Could/Won't
+- **User Stories**: Given-When-Then acceptance criteria
+- **Validation Checklist**: Automated completeness checks
+- **Integration Points**: AI command workflow guidance
+
+## Constitutional Compliance
+
+**Article III: Test-First**
+- [ ] Acceptance criteria written before implementation
+- [ ] Test scenarios clearly defined
+- [ ] Integration points identified
+
+**Article VI: Research**
+- [ ] Technology choices documented
+- [ ] Security considerations addressed
+- [ ] Performance requirements specified
+
+## Enhanced Error Handling
+
+- Template existence validation
+- Feature directory auto-discovery
+- Required sections validation
+- Acceptance criteria format checking
+- Clarification marker tracking
+
+## Integration Features
+
+- **Cross-platform script execution** with automatic detection
+- **Enhanced script integration** with Bash, PowerShell, and Python support
+- **Template variable processing** for AI optimization
+- **Automated validation** with detailed reporting
+- **Context-aware operation** using memory/context.md
+- **Progress tracking** with todo list integration
+- **Platform-agnostic operation** for Windows, Linux, and macOS