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

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

@@ -0,0 +1,315 @@
+---
+name: sp-task
+description: Generate and manage task breakdowns using AI-optimized templates
+allowed_tools:
+  - Read
+  - Write  
+  - Edit
+  - Bash
+  - TodoWrite
+---
+
+# /sp-task Command
+
+Generate task breakdowns from implementation plans using SpecPulse methodology with AI-optimized templates and enhanced validation.
+
+## Usage
+```
+/sp-task [action] [feature-directory]
+```
+
+Actions: `breakdown`, `update`, `status`, `execute` (defaults to `breakdown`)
+
+## Implementation
+
+When called with `/sp-task $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** to determine action:
+   - If `update`: Update task status and dependencies
+   - If `status`: Show comprehensive progress with metrics
+   - If `execute`: Execute task with script integration
+   - Otherwise: Generate task breakdown
+
+3. **For `/sp-task breakdown` or `/sp-task`:**
+   
+   a. **Check for decomposition**: Look for `specs/XXX-feature/decomposition/` directory
+   b. **If decomposed**:
+      - Read service definitions from decomposition
+      - Show service-specific plan files (auth-service-plan.md, user-service-plan.md, etc.)
+      - Generate tasks per service with service prefix (AUTH-T001, USER-T001)
+      - Create integration tasks (INT-T001) for cross-service work
+      - Structure: `tasks/XXX-feature/auth-service-tasks.md`, `integration-tasks.md`
+   c. **If not decomposed**:
+      - Show existing plan files and ask user to select
+      - Generate single task file with standard IDs (T001, T002)
+   c. **Enhanced validation** using cross-platform script:
+      ```bash
+      # Cross-platform detection
+      if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+          python scripts/sp-pulse-task.py "$FEATURE_DIR"
+      else
+          bash scripts/sp-pulse-task.sh "$FEATURE_DIR" || python scripts/sp-pulse-task.py "$FEATURE_DIR"
+      fi
+      ```
+   
+   d. **Read implementation plan** from selected plan file
+   
+   e. **Generate AI-optimized tasks** using template variables:
+      ```markdown
+      # Task List: {{ feature_name }}
+      ## Metadata
+      - **Total Tasks**: {{ task_count }}
+      - **Estimated Duration**: {{ total_duration }}
+      - **Plan Reference**: plan-{{ plan_version }}.md
+      - **Task Version**: {{ task_version }}
+      ```
+
+   f. **Generate structured task categories based on architecture**:
+      - **For decomposed services**:
+        * Service-specific tasks with bounded context
+        * Inter-service integration tasks
+        * Service deployment order tasks
+        * Contract testing tasks between services
+      - **For monolithic architecture**:
+        * Layer-based tasks (data, business, API)
+        * Module-specific tasks
+      - **Common categories**:
+        * Constitutional Gates Compliance
+        * Critical Path identification
+        * Parallel vs Sequential grouping
+        * Progress Tracking configuration
+
+   g. **For each task**, generate comprehensive metadata:
+      - **ID**: T[XXX] format (T001, T002)
+      - **Type**: setup, development, testing, documentation
+      - **Priority**: HIGH, MEDIUM, LOW
+      - **Estimate**: Hours or complexity points
+      - **Dependencies**: Task ID dependencies
+      - **Description**: Clear what needs to be done
+      - **Acceptance**: How to verify completion
+      - **Files**: Files to be created/modified
+      - **Assignable**: Role/skill required
+      - **Parallel**: Whether can run in parallel [P]
+
+   h. **Generate AI execution guidelines** with workflow integration:
+      ```markdown
+      ## AI Execution Strategy
+      ### Parallel Tasks (can be worked on simultaneously):
+      - T001, T002, T003: Independent tasks, no dependencies
+      ### Sequential Tasks (must be completed in order):
+      - T004 → T005 → T006: Dependency chain
+      ```
+
+   i. **Version management**: Check existing task files and create next version (task-001.md, task-002.md, etc.)
+   j. **Write comprehensive task breakdown** to `tasks/XXX-feature/task-XXX.md`
+
+4. **For `/sp-task update`:**
+   a. **Show existing task files**: List all task-XXX.md files in current feature directory
+   b. **Ask user to select**: Which task file to update
+   c. **Enhanced analysis** using cross-platform script:
+     ```bash
+     # Cross-platform detection
+     if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+         python scripts/sp-pulse-task.py "$FEATURE_DIR"
+     else
+         bash scripts/sp-pulse-task.sh "$FEATURE_DIR" || python scripts/sp-pulse-task.py "$FEATURE_DIR"
+     fi
+     ```
+   d. **Parse current tasks** from selected file with comprehensive status:
+     - Total tasks, completed, pending, blocked
+     - Parallel tasks identification
+     - Constitutional gates status
+     - Completion percentage calculation
+   e. **Interactive task updates**:
+     - Mark tasks as completed/in-progress/blocked
+     - Update dependencies and blockers
+     - Add newly discovered tasks with proper metadata
+     - Adjust estimates based on actual progress
+   f. **Generate updated progress tracking** YAML
+
+5. **For `/sp-task status`:**
+   a. **Show existing task files**: List all task-XXX.md files in current feature directory
+   b. **Ask user to select**: Which task file to show status for
+   c. **Enhanced reporting** from script output:
+     ```bash
+     TOTAL_TASKS=25
+     COMPLETED_TASKS=10
+     COMPLETION_PERCENTAGE=40%
+     CONSTITUTIONAL_GATES_PENDING=2
+     ```
+   d. **Display comprehensive progress**:
+     - Overall completion percentage
+     - Phase-by-phase progress
+     - Blocker identification and resolution
+     - Velocity metrics and estimates
+     - Constitutional gates compliance status
+
+6. **For `/sp-task execute`:**
+   a. **Show existing task files**: List all task-XXX.md files in current feature directory
+   b. **Ask user to select**: Which task file to execute from
+   c. **Ask user to specify**: Which specific task ID to execute
+   d. **Validate task readiness** using constitutional gates
+   e. **Execute task** using AI assistant capabilities:
+     ```markdown
+     ## Task Execution: {{ TASK_ID }}
+     **AI Assistant**: Claude/Gemini
+     **Method**: Direct implementation within AI session
+     **Status**: [ ] Pending → [-] In Progress → [x] Completed
+     ```
+   f. **Track execution results** and update status
+   g. **Update progress tracking** automatically
+
+## Enhanced Task Format
+
+### For Decomposed Services
+```markdown
+### Auth Service Tasks
+#### AUTH-T001: Initialize auth service structure
+- **Service**: Authentication
+- **Type**: setup
+- **Priority**: HIGH
+- **Dependencies**: None
+
+### User Service Tasks  
+#### USER-T001: Initialize user service structure
+- **Service**: User Management
+- **Type**: setup
+- **Priority**: HIGH
+- **Dependencies**: None
+
+### Integration Tasks
+#### INT-T001: Set up service communication
+- **Services**: Auth ↔ User
+- **Type**: integration
+- **Priority**: HIGH
+- **Dependencies**: AUTH-T001, USER-T001
+```
+
+### For Monolithic Architecture
+```markdown
+### Parallel Group A
+#### T001: Initialize project structure
+- **Type**: setup
+- **Priority**: HIGH
+- **Estimate**: 2 hours
+- **Dependencies**: None
+- **Description**: Set up project directory structure and configuration
+- **Acceptance**: All directories exist and config files are valid
+- **Files**: package.json, README.md, .gitignore
+- **Assignable**: developer
+- **Parallel**: [P]
+
+## Progress Tracking
+```yaml
+status:
+  total: 25
+  completed: 10
+  in_progress: 3
+  blocked: 0
+  
+metrics:
+  velocity: 2-3 tasks/day
+  estimated_completion: 2025-09-15
+  completion_percentage: 40%
+```
+
+## Constitutional Gates Integration
+
+Each task breakdown includes constitutional compliance validation:
+- **Simplicity Gate**: Tasks avoid unnecessary complexity
+- **Test-First Gate**: Test tasks before implementation tasks
+- **Integration-First Gate**: Real service integration preferred
+- **Research Gate**: Technology research tasks included
+
+## Examples
+
+### Generate tasks for decomposed spec
+```
+User: /sp-task breakdown
+```
+Detecting decomposition in `specs/001-authentication/decomposition/`...
+I will create:
+- `tasks/001-authentication/auth-service-tasks.md`
+- `tasks/001-authentication/user-service-tasks.md`
+- `tasks/001-authentication/integration-tasks.md`
+
+### Generate tasks for monolithic spec
+```
+User: /sp-task breakdown
+```
+No decomposition found. Creating single task file:
+- `tasks/001-authentication/task-001.md`
+
+### Execute service-specific task
+```
+User: /sp-task execute AUTH-T001
+```
+I will:
+- Run: Cross-platform detection and execution
+  ```bash
+  # Cross-platform detection
+  if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+      python scripts/sp-pulse-task.py "$FEATURE_DIR"
+  else
+      bash scripts/sp-pulse-task.sh "$FEATURE_DIR" || python scripts/sp-pulse-task.py "$FEATURE_DIR"
+  fi
+  ```
+- Create: AI-optimized task structure with template variables
+- Output: `TOTAL_TASKS=25, PARALLEL_TASKS=8, STATUS=generated`
+
+### Update task status
+```
+User: /sp-task update mark T001-T005 as completed
+```
+I will update task status and recalculate progress metrics.
+
+### Show comprehensive status
+```
+User: /sp-task status
+```
+I will display detailed progress with constitutional gates compliance.
+
+### Execute specific task
+```
+User: /sp-task execute T001
+```
+I will:
+- Validate: Constitutional gates compliance and task readiness
+- Execute: Cross-platform task execution
+  ```bash
+  # Cross-platform task execution
+  if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+      python scripts/sp-pulse-task.py "$FEATURE_DIR" "execute:$TASK_ID"
+  else
+      bash scripts/sp-pulse-task.sh "$FEATURE_DIR" "execute:$TASK_ID" || python scripts/sp-pulse-task.py "$FEATURE_DIR" "execute:$TASK_ID"
+  fi
+  ```
+- Track: Results and update progress automatically
+
+## Enhanced Features
+
+- **Cross-platform script execution** with automatic detection (Bash/Python)
+- **AI-optimized templates** with Jinja2-style variables
+- **Enhanced script integration** for validation and execution
+- **Constitutional gates compliance** tracking
+- **Parallel task identification** and execution
+- **Comprehensive progress tracking** with YAML configuration
+- **Automatic percentage calculation** and velocity metrics
+- **Task dependency management** with conflict detection
+- **Execution command generation** with script integration
+- **Platform-agnostic operation** for Windows, Linux, and macOS
+
+## Error Handling
+
+- Plan existence validation before task generation
+- Constitutional gates compliance checking
+- Template structure validation
+- Dependency conflict detection
+- Task execution error handling with rollback
+- Progress tracking validation and correction

specpulse/resources/commands/gemini/sp-continue.toml

@@ -0,0 +1,56 @@
+description = "Switch context and continue work on a specific feature"
+prompt = """
+Handle the /sp-continue command with arguments: {{args}}
+
+Parse arguments to extract feature name or ID
+
+## Feature Detection:
+1. 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")
+
+2. Validate feature exists:
+   - Check if feature directory has any files
+   - Verify feature structure is intact
+   - Report if feature not found
+
+3. Update context in memory/context.md:
+   - Switch current feature to selected feature
+   - Update timestamp and switch reason
+   - Preserve previous context data
+
+4. Switch git branch if in git repository:
+   - Checkout feature branch if it exists
+   - Report if branch doesn't exist
+   - Handle branch switching errors gracefully
+
+5. Display feature status:
+   - Show current progress percentage
+   - List next available actions
+   - Highlight any blockers or issues
+   - Show recent activity
+
+6. Suggest next steps based on feature state:
+   - If no spec files: /sp-spec <description>
+   - If spec but no plan: /sp-plan
+   - If plan but no tasks: /sp-task
+   - If tasks exist: Show task completion status and suggest next task
+
+## Supported Feature Identification:
+- By name: /sp-continue user-authentication
+- By ID: /sp-continue 001
+- By partial match: /sp-continue auth
+
+## Context Switching:
+1. Save previous context state
+2. Load new feature context
+3. Update memory/context.md
+4. Switch git branch if available
+5. Display feature status and next steps
+
+Examples:
+- /sp-continue user-authentication
+- /sp-continue 001
+- /sp-continue auth
+"""

specpulse/resources/commands/gemini/sp-decompose.toml

@@ -0,0 +1,54 @@
+[command]
+name = "sp-decompose"
+description = "Decompose large specifications into microservices, APIs, and smaller components"
+type = "spec-decomposition"
+
+[prompt]
+template = """
+Decompose the specification {{args}} into smaller, manageable components.
+
+Analysis required:
+1. Identify microservice boundaries using DDD principles
+2. Define API contracts with OpenAPI specifications
+3. Create interface specifications for each component
+4. Map data ownership and consistency boundaries
+5. Design communication patterns between services
+
+Generate:
+- Service definitions with clear responsibilities
+- API contracts in OpenAPI 3.0 format
+- Interface specifications in appropriate languages
+- Data models and schemas
+- Integration mapping diagram
+- Migration plan from monolith
+
+Apply these principles:
+- Domain-Driven Design for boundaries
+- SOLID principles for design
+- Single responsibility per service
+- Clear data ownership
+- Minimal coupling between services
+
+Output structure:
+specs/XXX-feature/decomposition/
+├── microservices.md
+├── api-contracts/
+├── interfaces/
+├── data-models/
+├── integration-map.md
+└── migration-plan.md
+"""
+
+[validation]
+required_outputs = [
+    "microservices.md",
+    "api-contracts",
+    "interfaces",
+    "integration-map.md"
+]
+
+[options]
+microservices = "Focus on service boundary identification"
+apis = "Generate detailed API contracts"
+interfaces = "Create interface specifications"
+all = "Complete decomposition analysis"

specpulse/resources/commands/gemini/sp-plan.toml

@@ -0,0 +1,68 @@
+description = "Generate or validate implementation plans with versioning"
+prompt = """
+Handle the /sp-plan command with arguments: {{args}}
+
+First, 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
+
+Parse arguments to determine action:
+- If "validate": Check plan against constitution
+- Otherwise: Generate new plan
+
+## For /sp-plan generate or /sp-plan:
+1. Show list of existing spec files in current feature directory
+2. Ask user which spec file to base plan on
+3. Read selected specification from @{specs/*/spec-XXX.md}
+
+4. Run Phase Gates checks:
+   - Constitutional compliance
+   - Simplicity check (≤3 modules)
+   - Test-first strategy defined
+   - Framework selection complete
+   - Research completed
+
+5. Generate plan sections:
+   - Technology stack
+   - Architecture overview
+   - Implementation phases
+   - API contracts
+   - Data models
+   - Testing strategy
+
+6. Track complexity:
+   - If >3 modules, document justification
+   - Create simplification roadmap
+
+7. Check existing plan files and create next version (plan-001.md, plan-002.md, etc.)
+8. Write plan to plans/XXX-feature/plan-XXX.md
+9. Run cross-platform validation:
+   - Linux/macOS: !{bash scripts/sp-pulse-plan.sh "XXX-feature"}
+   - Fallback: !{python scripts/sp-pulse-plan.py "XXX-feature"}
+
+## For /sp-plan validate:
+1. Show list of existing plan files in current feature directory
+2. Ask user which plan file to validate
+3. Read selected plan from @{plans/*/plan-XXX.md}
+4. Run cross-platform validation:
+   - Linux/macOS: !{bash scripts/sp-pulse-plan.sh "XXX-feature"}
+   - Fallback: !{python scripts/sp-pulse-plan.py "XXX-feature"}
+5. Verify Phase Gates compliance
+6. Check complexity tracking
+7. Ensure test-first approach
+8. Validate framework choices
+9. 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
+
+Examples:
+- /sp-plan generate
+- /sp-plan validate
+"""

specpulse/resources/commands/gemini/{pulse.toml → sp-pulse.toml}

@@ -6,9 +6,8 @@ Please follow these steps:
 
 1. Extract the feature name from the provided arguments
 2. Run the initialization script with cross-platform detection:
-   - Windows: !{powershell scripts/pulse-init.ps1 "{{args}}"}
-   - Linux/macOS: !{bash scripts/pulse-init.sh "{{args}}"}  
-   - Fallback: !{python scripts/pulse-init.py "{{args}"}
+   - Linux/macOS: !{bash scripts/sp-pulse-init.sh "{{args}}"}  
+   - Fallback: !{python scripts/sp-pulse-init.py "{{args}}"}
 3. Create the feature structure:
    - Generate feature ID (001, 002, etc.)
    - Create directories: specs/XXX-feature/, plans/XXX-feature/, tasks/XXX-feature/
@@ -16,12 +15,19 @@ Please follow these steps:
    - Update memory/context.md with current feature
    - Create git branch if in git repository
 
-4. Report the results showing:
+4. Suggest specification options:
+   - Generate 2-3 different specification suggestions based on the feature name
+   - Present options to user as numbered choices
+   - Ask user to choose one or provide their own specification description
+   - Guide user to use /sp-spec command after making selection
+
+5. Report the results showing:
    - Created structure paths
    - Feature ID and branch name
-   - Next steps for the user
+   - Specification suggestions for user to choose from
+   - Next steps guidance
 
 If no feature name is provided, ask the user for the feature name first.
 
-Example usage: /pulse user-authentication
+Example usage: /sp-pulse user-authentication
 """

specpulse/resources/commands/gemini/sp-spec.toml

@@ -0,0 +1,54 @@
+description = "Create or manage feature specifications with versioning"
+prompt = """
+Handle the /sp-spec command with arguments: {{args}}
+
+First, 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
+
+Parse the arguments to determine the action:
+- If starts with "create": Generate new specification
+- If starts with "update": Modify existing specification  
+- If starts with "validate": Check specification completeness
+- If no action specified: Default to "create" with full arguments as description
+
+## For /sp-spec create [description] or /sp-spec [description]:
+1. Read template from @{templates/spec.md}
+2. Parse the description to identify:
+   - Functional requirements (Must/Should/Could have)
+   - User stories and acceptance criteria
+   - Technical requirements
+3. Mark any uncertainties with [NEEDS CLARIFICATION: detail]
+4. Find current feature directory from detected context
+5. Check existing spec files and create next version (spec-001.md, spec-002.md, etc.)
+6. Write specification to specs/XXX-feature/spec-XXX.md
+7. Run cross-platform validation:
+   - Linux/macOS: !{bash scripts/sp-pulse-spec.sh "XXX-feature"}
+   - Fallback: !{python scripts/sp-pulse-spec.py "XXX-feature"}
+
+## For /sp-spec update:
+1. Show list of existing spec files in current feature directory
+2. Ask user which spec file to update
+3. Read selected specification file
+4. Ask user for clarifications or changes
+5. Update content while preserving structure
+6. Remove resolved [NEEDS CLARIFICATION] markers
+
+## For /sp-spec validate:
+1. Show list of existing spec files in current feature directory
+2. Ask user which spec file to validate
+3. Run cross-platform validation:
+   - Linux/macOS: !{bash scripts/sp-pulse-spec.sh "XXX-feature"}
+   - Fallback: !{python scripts/sp-pulse-spec.py "XXX-feature"}
+4. Check all required sections are filled
+5. Count [NEEDS CLARIFICATION] markers
+6. Verify acceptance criteria are testable
+7. Report validation results
+
+Examples:
+- /sp-spec user authentication with OAuth2 and email/password
+- /sp-spec update
+- /sp-spec validate
+"""

specpulse/resources/commands/gemini/sp-status.toml

@@ -0,0 +1,61 @@
+description = "Track progress across all features or specific feature details"
+prompt = """
+Handle the /sp-status command with arguments: {{args}}
+
+First, 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, work with all features
+
+Parse arguments to determine scope:
+- If feature name provided: Show detailed status for that feature
+- Otherwise: Show overview of all features
+
+## For /sp-status (all features overview):
+1. Scan all feature directories (specs/*, plans/*, tasks/*)
+2. Count features by status: active, completed, in_progress, paused
+3. Calculate overall project progress
+4. Show summary statistics:
+   ```
+   TOTAL_FEATURES=5
+   ACTIVE_FEATURES=2
+   COMPLETED_FEATURES=1
+   IN_PROGRESS_FEATURES=1
+   PAUSED_FEATURES=1
+   OVERALL_PROGRESS=42%
+   ```
+5. List all features with their status and progress percentage
+6. Highlight current active feature from context
+
+## For /sp-status [feature-name] (detailed feature status):
+1. Detect feature directory using context detection logic
+2. Read all task files in the feature's tasks directory
+3. Calculate completion percentage based on task status
+4. Show detailed breakdown:
+   ```
+   FEATURE: 001-user-authentication
+   STATUS: active
+   PROGRESS: 65%
+   SPECS: 2 files
+   PLANS: 1 file
+   TASKS: 1 file (25 total tasks)
+   COMPLETED_TASKS: 16
+   IN_PROGRESS_TASKS: 5
+   BLOCKED_TASKS: 1
+   LAST_UPDATED: 2025-01-09
+   ```
+5. Show phase-by-phase progress
+6. List any blockers or issues
+7. Provide recommendations for next steps
+
+Progress calculation:
+- Scan task files for completion status: [x] completed, [ ] pending, [-] in progress, [!] blocked
+- Calculate percentages: completed / total * 100
+- Track status: active, completed, in_progress, paused, blocked
+
+Examples:
+- /sp-status
+- /sp-status user-authentication
+- /sp-status 001
+"""