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

specpulse/resources/templates/spec.md

@@ -1,291 +1,125 @@
-<!-- SpecPulse Specification Template v3.0 - SDD Methodology -->
-<!-- AI Instructions: 
-     1. Focus on WHAT users need and WHY, not HOW to implement
-     2. Mark ALL uncertainties with [NEEDS CLARIFICATION: specific question]
-     3. Do NOT include implementation details (no tech stack, APIs, code)
-     4. Ensure all requirements are testable and unambiguous
+<!-- SpecPulse Specification Template v4.0 - AI-Optimized -->
+<!-- AI Instructions:
+    1. Replace all {{variable}} placeholders with actual values
+    2. Fill sections based on user input and requirements analysis
+    3. Mark ALL uncertainties with [NEEDS CLARIFICATION: specific question]
+    4. Keep requirements testable and unambiguous
+    5. Focus on WHAT and WHY, not HOW
 -->
 
-# Specification: [FEATURE_NAME]
+# Specification: {{ feature_name }}
 
 ## Metadata
-- **ID**: SPEC-[XXX]
-- **Branch**: [auto-generated-branch-name]
-- **Created**: [DATE]
-- **Author**: [USER]
-- **AI Assistant**: [CLAUDE|GEMINI]
+- **ID**: SPEC-{{ feature_id }}
+- **Branch**: {{ branch_name }}
+- **Created**: {{ date }}
+- **Author**: {{ author }}
+- **AI Assistant**: {{ ai_assistant }}
 - **Version**: 1.0.0
-- **Status**: DRAFT | IN_REVIEW | APPROVED | IMPLEMENTED
+- **Status**: DRAFT
 
 ## Executive Summary
-[One paragraph: What problem does this solve? Who benefits? What's the value?]
+{{ executive_summary | default("Brief description of what this feature does and why it's needed") }}
 
-## Intent Statement
-**The user's original request:**
+## User Request
 ```
-[Exact user prompt/description that initiated this specification]
+{{ user_input }}
 ```
 
 ## Problem Statement
 
 ### Current State
-[What's the situation now? What pain points exist?]
+{{ current_state | default("Describe the current situation and pain points") }}
 
-### Desired State
-[What should the situation be after implementation?]
-
-### Gap Analysis
-[What's preventing us from reaching the desired state?]
+### Desired State  
+{{ desired_state | default("Describe what should be achieved after implementation") }}
 
 ## Clarifications Needed
-<!-- AI: List ALL ambiguities from the user prompt -->
-- [NEEDS CLARIFICATION: Authentication method not specified - OAuth, JWT, Session?]
-- [NEEDS CLARIFICATION: User role definitions not provided - Admin, User, Guest?]
-- [NEEDS CLARIFICATION: Data retention policy not mentioned - 30 days, 1 year, forever?]
+<!-- List ALL ambiguities from user input -->
+{% if clarifications %}
+{% for clarification in clarifications %}
+- [NEEDS CLARIFICATION: {{ clarification }}]
+{% endfor %}
+{% else %}
+- [NEEDS CLARIFICATION: Add specific questions based on user input]
+{% endif %}
 
-## User Personas
+## User Stories
 
-### Primary User: [Name]
-- **Role**: [Job title/function]
-- **Goals**: [What they want to achieve]
-- **Pain Points**: [Current frustrations]
-- **Success Metrics**: [How they measure success]
+### Primary Stories
+{% for story in user_stories %}
+#### Story {{ loop.index }}: {{ story.title }}
+**As a** {{ story.user_type }}
+**I want to** {{ story.action }}
+**So that** {{ story.benefit }}
 
-### Secondary User: [Name]
-- **Role**: [Job title/function]
-- **Goals**: [What they want to achieve]
-- **Pain Points**: [Current frustrations]
-- **Success Metrics**: [How they measure success]
+**Acceptance Criteria:**
+{% for criteria in story.acceptance_criteria %}
+- Given {{ criteria.given }}, when {{ criteria.when }}, then {{ criteria.then }}
+{% endfor %}
+{% endfor %}
 
 ## Functional Requirements
 
-### Core Requirements (MUST Have)
-<!-- Requirements without which the feature cannot function -->
-
-**FR-001**: [Requirement statement]
-- **Rationale**: [Why this is needed]
-- **Acceptance Criteria**:
-  - Given [context], when [action], then [outcome]
-  - Given [context], when [action], then [outcome]
-- **Testable**: Yes - [How to test]
-- **Dependencies**: [None | FR-XXX]
-
-**FR-002**: [Requirement statement]
-- **Rationale**: [Why this is needed]
-- **Acceptance Criteria**:
-  - Given [context], when [action], then [outcome]
-  - Given [context], when [action], then [outcome]
-- **Testable**: Yes - [How to test]
-- **Dependencies**: [None | FR-XXX]
-
-### Enhanced Requirements (SHOULD Have)
-<!-- Requirements that significantly improve the feature -->
-
-**FR-003**: [Requirement statement]
-[Same structure as above]
+### MUST Have Requirements
+{% for req in must_requirements %}
+**FR-{{ "%03d" | format(loop.index0 + 1) }}**: {{ req.statement }}
+- **Rationale**: {{ req.rationale }}
+- **Testable**: Yes
+{% endfor %}
 
-### Optional Requirements (COULD Have)
-<!-- Nice-to-have requirements for future consideration -->
-
-**FR-004**: [Requirement statement]
-[Same structure as above]
+### SHOULD Have Requirements
+{% for req in should_requirements %}
+**FR-{{ "%03d" | format(loop.index0 + len(must_requirements) + 1) }}**: {{ req.statement }}
+- **Rationale**: {{ req.rationale }}
+- **Testable**: Yes
+{% endfor %}
 
 ## Non-Functional Requirements
 
-### Performance Requirements
-- **NFR-001**: Response time SHALL be < [X]ms for [Y]% of requests
-  - [NEEDS CLARIFICATION: Acceptable response time not specified]
-- **NFR-002**: System SHALL handle [X] concurrent users
-  - [NEEDS CLARIFICATION: Expected user load not specified]
-
-### Security Requirements
-- **NFR-003**: All data SHALL be encrypted in transit
-- **NFR-004**: Authentication SHALL be required for [actions]
-  - [NEEDS CLARIFICATION: Which actions require authentication?]
-
-### Usability Requirements
-- **NFR-005**: Interface SHALL be accessible (WCAG 2.1 Level AA)
-- **NFR-006**: Actions SHALL be reversible where possible
-  - [NEEDS CLARIFICATION: Which actions should be reversible?]
-
-### Reliability Requirements
-- **NFR-007**: System SHALL have [X]% uptime
-  - [NEEDS CLARIFICATION: Uptime requirement not specified]
-- **NFR-008**: Data SHALL be backed up every [X] hours
-  - [NEEDS CLARIFICATION: Backup frequency not specified]
-
-## User Stories
+### Performance
+- Response time < {{ performance.response_time | default("200ms") }}
+- Support {{ performance.concurrent_users | default("1000") }} concurrent users
 
-### Epic: [High-level Feature Group]
-
-#### Story 001: [User can do primary action]
-**As a** [specific user type]  
-**I want to** [specific action/feature]  
-**So that** [specific benefit/value]  
-
-**Acceptance Criteria:**
-```gherkin
-Scenario: [Happy path scenario]
-  Given I am a [user type]
-  And [precondition]
-  When I [action]
-  Then [expected outcome]
-  And [additional outcome]
-
-Scenario: [Edge case scenario]
-  Given I am a [user type]
-  And [different precondition]
-  When I [action]
-  Then [different outcome]
-```
-
-**Test Cases:**
-- TC-001: [Test case description]
-- TC-002: [Test case description]
-
-#### Story 002: [User can handle errors]
-[Same structure as above]
+### Security
+- All data encrypted in transit
+- {{ security.authentication | default("Authentication required for sensitive actions") }}
 
 ## Acceptance Scenarios
 
-### Critical Path Scenarios
-<!-- These MUST work for the feature to be considered complete -->
-
-1. **Scenario**: [Name]
-   - **Setup**: [Initial conditions]
-   - **Actions**: [Step-by-step user actions]
-   - **Expected Result**: [What should happen]
-   - **Validation**: [How to verify success]
-
-### Edge Cases
-<!-- Unusual but valid scenarios that must be handled -->
-
-1. **Scenario**: [Empty input handling]
-   - **Setup**: [No data provided]
-   - **Expected Result**: [Graceful error message]
-
-2. **Scenario**: [Maximum input handling]
-   - **Setup**: [Maximum allowed data]
-   - **Expected Result**: [System handles without error]
-
-### Error Scenarios
-<!-- How the system should handle various failure modes -->
+### Critical Path
+1. **Scenario**: {{ primary_scenario.name }}
+   - **When**: {{ primary_scenario.action }}
+   - **Then**: {{ primary_scenario.result }}
 
-1. **Error**: [Network failure]
-   - **User Impact**: [What user sees]
-   - **Recovery**: [How user can proceed]
+### Error Cases
+1. **Scenario**: {{ error_scenario.name }}
+   - **When**: {{ error_scenario.action }}
+   - **Then**: {{ error_scenario.result }}
 
-## Constraints and Assumptions
-
-### Constraints
-<!-- Hard limitations that cannot be changed -->
-- [Legal/Regulatory constraint]
-- [Technical constraint]
-- [Business constraint]
-
-### Assumptions
-<!-- Things we assume to be true; mark unclear ones -->
-- Users have [basic technical knowledge] [NEEDS CLARIFICATION: User skill level?]
-- System will run on [modern browsers] [NEEDS CLARIFICATION: Browser support needed?]
-- Data volume will not exceed [X] [NEEDS CLARIFICATION: Expected data volume?]
+## Success Metrics
+- Adoption rate: {{ metrics.adoption_rate | default("80% within 30 days") }}
+- Success rate: {{ metrics.success_rate | default("95% of attempts") }}
+- User satisfaction: {{ metrics.satisfaction | default("8/10 NPS") }}
 
 ## Out of Scope
 <!-- Explicitly state what this feature will NOT do -->
-- This feature will NOT [handle X]
-- This feature will NOT [integrate with Y]
-- This feature will NOT [support Z]
+{% for item in out_of_scope %}
+- This feature will NOT {{ item }}
+{% endfor %}
 
-## Success Metrics
-
-### Key Performance Indicators (KPIs)
-- **Adoption Rate**: [X]% of users use feature within [Y] days
-  - [NEEDS CLARIFICATION: Target adoption rate?]
-- **Success Rate**: [X]% of attempts complete successfully
-  - [NEEDS CLARIFICATION: Acceptable success rate?]
-- **User Satisfaction**: [X] NPS score
-  - [NEEDS CLARIFICATION: Target satisfaction score?]
+## Dependencies
+{% for dep in dependencies %}
+- {{ dep }}
+{% endfor %}
 
-### Validation Criteria
+## Validation Checklist
 - [ ] All MUST requirements implemented
 - [ ] All acceptance criteria pass
 - [ ] No [NEEDS CLARIFICATION] markers remain
 - [ ] Performance targets met
 - [ ] Security requirements validated
 
-## Dependencies
-
-### Internal Dependencies
-- [Other feature that must exist]
-- [Shared component required]
-
-### External Dependencies
-- [Third-party service required] [NEEDS CLARIFICATION: Which service?]
-- [External API needed] [NEEDS CLARIFICATION: API details?]
-
-## Risks and Mitigations
-
-| Risk | Probability | Impact | Mitigation | Owner |
-|------|------------|--------|------------|-------|
-| [Unclear requirements] | High | High | Use [NEEDS CLARIFICATION] markers | Product Owner |
-| [Scope creep] | Medium | High | Strict change control process | Project Manager |
-| [Technical complexity] | Low | Medium | Research spike before implementation | Tech Lead |
-
-## Timeline Considerations
-
-### Milestones
-- Specification Approval: [DATE or NEEDS CLARIFICATION]
-- Implementation Start: [DATE or NEEDS CLARIFICATION]
-- Testing Complete: [DATE or NEEDS CLARIFICATION]
-- Production Release: [DATE or NEEDS CLARIFICATION]
-
-### Dependencies on Timeline
-- [External factor affecting timeline]
-- [Resource availability consideration]
-
-## Glossary
-<!-- Define domain-specific terms -->
-- **[Term]**: [Definition]
-- **[Acronym]**: [Expansion and explanation]
-
-## Appendix
-
-### Mockups/Wireframes
-[Reference to attached designs or describe textually]
-
-### Related Specifications
-- [Link to related SPEC-XXX]
-- [Link to parent epic specification]
-
-### Change Log
-| Version | Date | Author | Changes |
-|---------|------|--------|---------|
-| 1.0.0 | [DATE] | [AI] | Initial specification from user prompt |
-
-## Specification Validation Checklist
-
-### Completeness
-- [ ] All user stories have acceptance criteria
-- [ ] All requirements are numbered for traceability
-- [ ] Success metrics are defined and measurable
-- [ ] All scenarios have expected outcomes
-
-### Clarity
-- [ ] No ambiguous language ("should", "might", "possibly")
-- [ ] All technical terms defined in glossary
-- [ ] Requirements are atomic (one requirement per item)
-- [ ] All [NEEDS CLARIFICATION] items are specific questions
-
-### Testability
-- [ ] Every requirement has acceptance criteria
-- [ ] All acceptance criteria are verifiable
-- [ ] Test cases map to requirements
-- [ ] Performance targets are measurable
-
-### Consistency
-- [ ] No contradicting requirements
-- [ ] Terminology used consistently throughout
-- [ ] All cross-references are valid
-- [ ] Scope boundaries are clear
-
 ---
-**Note**: This specification is the source of truth. Implementation must trace back to these requirements. Any changes require specification update first.
+**Generated by**: {{ ai_assistant }} on {{ date }}
+**Next Steps**: Use `/plan` to create implementation plan

specpulse/resources/templates/task.md

@@ -1,143 +1,164 @@
-<!-- SpecPulse Task List Template v2.0 -->
-<!-- AI Instructions: Generate from implementation plan -->
+<!-- SpecPulse Task List Template v3.0 - AI-Optimized -->
+<!-- AI Instructions: Generate from implementation plan using constitutional gates -->
 
-# Task List: [FEATURE_NAME]
+# Task List: {{ feature_name }}
 
 ## Metadata
-- **Plan Reference**: [PLAN_ID]
-- **Total Tasks**: [COUNT]
-- **Estimated Duration**: [TOTAL_HOURS]
-- **Parallel Groups**: [COUNT]
+- **Plan Reference**: SPEC-{{ feature_id }}
+- **Total Tasks**: {{ task_count }}
+- **Estimated Duration**: {{ total_duration }}
+- **Parallel Groups**: {{ parallel_groups }}
 
 ## Task Organization
 
-### Parallel Group A
+{% for group in parallel_groups %}
+### Parallel Group {{ loop.index }}
 *These tasks can be executed simultaneously*
 
-#### T001: [Task Name]
-- **Type**: [setup|development|testing|documentation]
-- **Priority**: [HIGH|MEDIUM|LOW]
-- **Estimate**: [hours]
-- **Dependencies**: None
-- **Description**: [What needs to be done]
-- **Acceptance**: [How to verify completion]
-- **Files**: [List of files to be created/modified]
-- **Assignable**: [role/skill required]
-
-#### T002: [Task Name]
-[Same structure as above]
+{% for task in group.tasks %}
+#### {{ task.id }}: {{ task.name }}
+- **Type**: {{ task.type }}
+- **Priority**: {{ task.priority }}
+- **Estimate**: {{ task.estimate }}
+- **Dependencies**: {{ task.dependencies | join(", ") | default("None") }}
+- **Description**: {{ task.description }}
+- **Acceptance**: {{ task.acceptance }}
+- **Files**: {{ task.files | join(", ") }}
+- **Assignable**: {{ task.assignable }}
+{% endfor %}
+{% endfor %}
 
 ### Sequential Tasks
 *These tasks must be completed in order*
 
-#### T003: [Task Name]
-- **Dependencies**: T001
-[Rest of structure]
+{% for task in sequential_tasks %}
+#### {{ task.id }}: {{ task.name }}
+- **Dependencies**: {{ task.dependencies | join(", ") }}
+- **Type**: {{ task.type }}
+- **Priority**: {{ task.priority }}
+- **Estimate**: {{ task.estimate }}
+- **Description**: {{ task.description }}
+- **Acceptance**: {{ task.acceptance }}
+{% endfor %}
 
 ### Critical Path
 *Tasks that directly impact timeline*
 
-1. T001 → T003 → T007
-2. Estimated critical path duration: [hours]
-
-## Task Details
-
-### Setup Tasks (T001-T009)
-- [ ] T001: Initialize project structure
-- [ ] T002: Install dependencies
-- [ ] T003: Configure development environment
-- [ ] T004: Setup database
-- [ ] T005: Configure CI/CD
+{% for path in critical_path %}
+{{ loop.index }}. {{ path.tasks | join(" → ") }}
+{% endfor %}
+- Estimated critical path duration: {{ critical_path_duration }}
 
-### Test Tasks [P] (T010-T019)
-- [ ] T010: Write unit tests for [component]
-- [ ] T011: Write integration tests for [feature]
-- [ ] T012: Write E2E tests for user flow
-- [ ] T013: Performance test setup
+## Constitutional Gates Compliance
 
-### Development Tasks (T020-T049)
-- [ ] T020: Implement [component]
-- [ ] T021: Create [feature]
-- [ ] T022: Integrate [service]
+### Pre-Implementation Validation
+{% for gate in constitutional_gates %}
+#### {{ gate.name }}
+- [ ] {{ gate.check_1 }}
+- [ ] {{ gate.check_2 }}
+- [ ] {{ gate.check_3 }}
+- [ ] {{ gate.check_4 }}
+**Status**: {{ gate.status | default("PENDING") }}
+{% endfor %}
 
-### Integration Tasks (T050-T059)
-- [ ] T050: Connect to database
-- [ ] T051: Integrate external APIs
-- [ ] T052: Setup middleware
+## Task Details by Category
 
-### Polish Tasks [P] (T060-T069)
-- [ ] T060: Documentation
-- [ ] T061: Performance optimization
-- [ ] T062: Security hardening
-- [ ] T063: Deployment preparation
+{% for category in task_categories %}
+### {{ category.name }} Tasks {% if category.parallel %}[P]{% endif %}
+{% for task in category.tasks %}
+- [ ] {{ task.id }}: {{ task.name }}
+{% endfor %}
+{% endfor %}
 
 ## Execution Schedule
 
-### Day 1-2
-- Morning: T001, T002, T003 (parallel)
-- Afternoon: T004, T005
-
-### Day 3-4
-- Morning: T010-T013 (parallel, TDD)
-- Afternoon: T020, T021
-
-### Day 5-6
-- Full days: T022-T049 (development sprint)
-
-### Day 7
-- Morning: T050-T052 (integration)
-- Afternoon: T060-T063 (polish, parallel)
+{% for phase in execution_schedule %}
+### {{ phase.name }}
+{% for time_block in phase.time_blocks %}
+- {{ time_block.timing }}: {{ time_block.tasks | join(", ") }}{% if time_block.parallel %} (parallel){% endif %}
+{% endfor %}
+{% endfor %}
 
 ## Progress Tracking
 ```yaml
 status:
-  total: [count]
+  total: {{ task_count }}
   completed: 0
   in_progress: 0
   blocked: 0
   
 metrics:
-  velocity: [tasks/day]
-  estimated_completion: [date]
+  velocity: {{ velocity | default("2-3 tasks/day") }}
+  estimated_completion: {{ estimated_completion }}
   blockers: []
   
 parallel_groups:
-  - name: "Setup"
-    tasks: [T001, T002, T003]
-    can_start: immediately
-  - name: "Tests"
-    tasks: [T010, T011, T012, T013]
-    can_start: after_setup
-  - name: "Polish"
-    tasks: [T060, T061, T062, T063]
-    can_start: after_development
+{% for group in parallel_groups %}
+  - name: "{{ group.name }}"
+    tasks: [{{ group.tasks | map(attribute='id') | join(", ") }}]
+    can_start: {{ group.can_start }}
+{% endfor %}
+
+sequential_tasks:
+{% for task in sequential_tasks %}
+  - name: "{{ task.name }}"
+    id: {{ task.id }}
+    dependencies: [{{ task.dependencies | join(", ") }}]
+{% endfor %}
 ```
 
 ## Task Execution Commands
 
 ### For parallel tasks:
 ```bash
-# Execute multiple [P] tasks simultaneously
-parallel_tasks="T001 T002 T003"
+# Execute parallel tasks using SpecPulse scripts
+{% for group in parallel_groups %}
+# {{ group.name }} tasks
+parallel_tasks="{{ group.tasks | map(attribute='id') | join(" ") }}"
 for task in $parallel_tasks; do
     echo "Starting $task in parallel..."
-    # Execute task
+    ./scripts/execute-task.sh "$task" &
 done
+wait  # Wait for all parallel tasks to complete
+{% endfor %}
 ```
 
 ### For sequential tasks:
 ```bash
-# Execute tasks in order
-sequential_tasks="T004 T005 T020"
-for task in $sequential_tasks; do
-    echo "Executing $task..."
-    # Execute task
-    # Wait for completion before next
-done
+# Execute tasks in dependency order
+{% for task in sequential_tasks %}
+# {{ task.name }} ({{ task.id }})
+echo "Executing {{ task.id }}..."
+./scripts/execute-task.sh "{{ task.id }}"
+# Check success before proceeding
+if [ $? -eq 0 ]; then
+    echo "{{ task.id }} completed successfully"
+else
+    echo "{{ task.id }} failed - halting execution"
+    exit 1
+fi
+{% endfor %}
 ```
 
-## Notes
-- Tasks marked with [P] can be executed in parallel
-- Update progress tracking after each task completion
-- If blocked, document reason and mitigation
-- Adjust estimates based on actual velocity
+## AI Integration Notes
+
+### Constitutional Gates
+- All tasks MUST pass constitutional compliance before implementation
+- Use `/validate` command to check compliance status
+- Mark gates as completed only after actual validation
+
+### Progress Tracking
+- Update task status in real-time using `/status` command
+- Document blockers immediately when identified
+- Use velocity metrics to refine future estimates
+
+### Quality Assurance
+- Each task requires specific acceptance criteria
+- Test-first development mandated by Article III
+- Integration tests required before deployment
+
+---
+**Generated by**: {{ ai_assistant }} on {{ date }}
+**Feature**: {{ feature_name }}
+**Constitutional Gates**: {{ constitutional_status | default("PENDING VALIDATION") }}
+**Next Steps**: Execute tasks following constitutional order