specpulse 1.0.3__py3-none-any.whl → 1.0.5__py3-none-any.whl

specpulse/__init__.py

@@ -3,7 +3,7 @@ SpecPulse: Specification-Driven Development Framework
 Built for the AI era
 """
 
-__version__ = "1.0.3"
+__version__ = "1.0.5"
 __author__ = "SpecPulse"
 __url__ = "https://github.com/specpulse"
 

specpulse/resources/commands/claude/plan.md

@@ -1,54 +1,184 @@
-# /plan
+---
+name: plan
+description: Generate or validate implementation plans using AI-optimized templates
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - TodoWrite
+---
 
-Generate implementation plans using SpecPulse methodology.
+# /plan Command
+
+Generate implementation plans from specifications following SpecPulse methodology with constitutional compliance and AI-optimized templates.
 
 ## Usage
 ```
-/plan generate
-/plan validate
-```
-
-## Commands
-
-### generate
-Create implementation plan from specification:
-1. Run Phase Gates checks:
-   - Constitutional compliance
-   - Simplicity check (≤3 modules)
-   - Test-first strategy defined
-   - Framework selection complete
-   - Research completed
-
-2. Generate plan sections:
-   - Technology stack
-   - Architecture overview
-   - Implementation phases
-   - API contracts
-   - Data models
-   - Testing strategy
-
-3. Track complexity:
-   - If >3 modules, document justification
-   - Create simplification roadmap
-
-4. Write to plans/[feature]/plan.md
-
-### validate
-Check plan against constitution:
-1. Verify Phase Gates passed
-2. Check complexity tracking
-3. Ensure test-first approach
-4. Validate framework choices
-
-## 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
-```
-/plan generate
-```
+/plan [action] [feature-directory]
+```
+
+Actions: `generate`, `validate`, `optimize` (defaults to `generate`)
+
+## Implementation
+
+When called with `/plan $ARGUMENTS`, I will:
+
+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. **Find and validate specification** from current context or provided directory
+   
+   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`:**
+   - **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
+```
+
+### 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

@@ -1,36 +1,91 @@
-# /pulse
+---
+name: pulse
+description: Initialize a new feature with SpecPulse framework
+allowed_tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - TodoWrite
+---
 
-Initialize a new feature with SpecPulse framework.
+# /pulse Command
+
+Initialize a new feature following SpecPulse methodology with constitutional compliance.
 
 ## Usage
 ```
-/pulse init <feature-name>
+/pulse <feature-name> [feature-id]
 ```
 
-## What This Does
-1. Runs `scripts/pulse-init.sh <feature-name>` to:
-   - Create feature ID (001, 002, etc.)
-   - Create branch name (001-feature-name)
-   - Create directories: specs/, plans/, tasks/
-   - Copy templates to feature directories
-   - Update memory/context.md
-   - Create git branch if in git repo
+## Implementation
+
+When called with `/pulse $ARGUMENTS`, I will:
+
+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. **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
 
-2. Reports the created structure back to user
+**Article II: Anti-Abstraction**  
+- [ ] Direct template usage (no wrapper layers)
+- [ ] Minimal initial structure
+- [ ] Framework-ready files
 
 ## Example
 ```
-/pulse init user-authentication
+User: /pulse user-authentication-oauth2
 ```
 
-Creates:
-- Branch: 001-user-authentication
-- specs/001-user-authentication/spec.md
-- plans/001-user-authentication/plan.md
-- tasks/001-user-authentication/tasks.md
-
-## Next Steps
-After initialization, use:
-- `/spec create` to write the specification
-- `/plan generate` to create implementation plan
-- `/task breakdown` to generate tasks
+I will:
+- 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,47 +1,160 @@
-# /spec
+---
+name: spec
+description: Create or manage feature specifications using AI-optimized templates
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - TodoWrite
+---
 
-Create or update feature specifications using SpecPulse.
+# /spec Command
+
+Create, update, or validate feature specifications using SpecPulse methodology with AI-optimized templates.
 
 ## Usage
 ```
-/spec create <description>
-/spec update
-/spec validate
-```
-
-## Commands
-
-### create
-Generate a specification from user requirements:
-1. Parse the user's description
-2. Identify functional requirements
-3. Create user stories
-4. Mark uncertainties with [NEEDS CLARIFICATION]
-5. Write to specs/[feature]/spec.md
-
-### update
-Update existing specification:
-1. Read current spec.md
-2. Apply changes based on clarifications
-3. Remove resolved [NEEDS CLARIFICATION] markers
-4. Update acceptance criteria
-
-### validate
-Check specification completeness:
-1. Ensure all sections are filled
-2. Check for remaining [NEEDS CLARIFICATION] markers
-3. Verify acceptance criteria are testable
-4. Confirm technical specs are defined
-
-## Template Structure
-- Project Overview
-- Functional Requirements (Must/Should/Could)
-- User Stories with Acceptance Criteria
-- Technical Specifications
-- Clarifications Needed
-- Validation Checklist
-
-## Example
-```
-/spec create "Build a user authentication system with email/password and OAuth2"
-```
+/spec [action] [description|feature-name]
+```
+
+Actions: `create`, `update`, `validate`, `clarify` (defaults to `create`)
+
+## Implementation
+
+When called with `/spec $ARGUMENTS`, I will:
+
+1. **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]`:**
+   - Read AI-optimized template from `templates/spec.md`
+   - Parse the description to identify:
+     - 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 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`:**
+   - 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 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 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
+- Constitutional compliance sections
+- Testable acceptance criteria
+- Automated validation
+
+### Updating existing specification
+```
+User: /spec update add password complexity requirements
+```
+I will read the current spec, update password requirements, and validate changes.
+
+### Validating specification
+```
+User: /spec validate
+```
+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