specweave 0.1.0

package/src/skills/increment-quality-judge/test-cases/test-2-poor-spec.yaml

@@ -0,0 +1,108 @@
+---
+name: "Quality Assessment - Poor Spec Needing Improvement"
+description: "Evaluate a vague specification with untestable criteria, triggering feedback loop"
+skill: increment-quality-judge
+priority: P1
+estimated_time: "2-3 minutes"
+
+input:
+  prompt: "Assess the quality of the payment processing spec"
+  spec_content: |
+    # Payment Processing
+
+    ## Overview
+    Add payment feature to the app.
+
+    ## Requirements
+    - Users can make payments
+    - System should be secure
+    - Payments should be fast
+    - Handle errors properly
+
+    ## Technical Details
+    - Use some payment provider
+    - Store payment info
+    - Send receipts
+
+expected_output:
+  overall_score: 0.50-0.70
+  score_range: "needs_work"  # Below 70
+
+  dimension_scores:
+    clarity:
+      max: 0.65
+      rationale: "Vague problem statement, objectives unclear"
+
+    testability:
+      max: 0.55
+      rationale: "Acceptance criteria not measurable (no metrics, thresholds)"
+
+    completeness:
+      max: 0.60
+      rationale: "Missing error handling details, security specs, performance targets"
+
+    feasibility:
+      max: 0.70
+      rationale: "No timeline, resource requirements unclear"
+
+    maintainability:
+      max: 0.65
+      rationale: "Lacks modularity, extension points undefined"
+
+    edge_cases:
+      max: 0.50
+      rationale: "No failure scenarios, retry logic, or edge case handling"
+
+  issues_found:
+    count: 5-8
+    severity_breakdown:
+      critical: 0-1
+      major: 3-5
+      minor: 2-3
+
+  typical_issues:
+    - severity: "major"
+      description: "Acceptance criteria not testable"
+      location: "Requirements section"
+      suggestion: "Add measurable metrics (e.g., 'Payment completes in <3s')"
+
+    - severity: "major"
+      description: "Security requirements too vague"
+      location: "Technical Details"
+      suggestion: "Specify: PCI-DSS compliance, encryption standards (TLS 1.3), tokenization"
+
+    - severity: "major"
+      description: "No error handling specification"
+      location: "Requirements"
+      suggestion: "Define error scenarios: payment declined, timeout, network failure"
+
+    - severity: "minor"
+      description: "Payment provider not specified"
+      location: "Technical Details"
+      suggestion: "Choose provider: Stripe, PayPal, or Square"
+
+  suggestions:
+    count: 5-8
+    priority_breakdown:
+      high: 3-5
+      medium: 2-3
+      low: 0-1
+
+  confidence: 0.85-0.95  # High confidence even for poor spec
+
+validation:
+  - "Overall score < 0.70"
+  - "Testability dimension < 0.60"
+  - "At least 5 issues found"
+  - "At least 3 major issues"
+  - "At least 5 suggestions provided"
+  - "High priority suggestions >= 3"
+  - "Confidence >= 0.85"
+
+success_criteria:
+  - "Score accurately reflects poor quality"
+  - "All 6 dimensions show low scores"
+  - "Issues clearly documented with locations"
+  - "Actionable suggestions with examples"
+  - "Would trigger feedback loop (score < 0.80)"
+---

package/src/skills/increment-quality-judge/test-cases/test-3-export-suggestions.yaml

@@ -0,0 +1,87 @@
+---
+name: "Export Suggestions to Tasks"
+description: "Quality assessment with suggestions exported to tasks.md"
+skill: increment-quality-judge
+priority: P2
+estimated_time: "2-3 minutes"
+
+input:
+  prompt: "Assess quality and export suggestions to tasks"
+  spec_content: |
+    # User Profile Management
+
+    ## Overview
+    Allow users to manage their profile information.
+
+    ## Acceptance Criteria
+    - User can update profile (name, email, avatar)
+    - Changes saved successfully
+    - Validation for email format
+
+    ## Security
+    - Email verification required for email changes
+
+  export_to_tasks: true
+  increment_id: "0025-user-profile"
+
+expected_output:
+  overall_score: 0.70-0.80
+  score_range: "acceptable"  # 70-79
+
+  issues_found:
+    count: 3-5
+    typical_issues:
+      - "Performance requirements not specified"
+      - "Avatar upload constraints unclear (size, format)"
+      - "Concurrent edit conflict resolution not defined"
+
+  suggestions:
+    count: 3-5
+    typical_suggestions:
+      - priority: "high"
+        description: "Add performance requirements"
+        example: "Profile update completes in <1s, avatar upload <5s"
+
+      - priority: "high"
+        description: "Specify avatar constraints"
+        example: "Max size: 5MB, formats: JPG/PNG/WebP, dimensions: 512x512"
+
+      - priority: "medium"
+        description: "Define edit conflict resolution"
+        example: "Last-write-wins or optimistic locking with version field"
+
+  export_result:
+    file_path: ".specweave/increments/0025-user-profile/tasks.md"
+    tasks_added: 3-5
+    format: "markdown checklist"
+
+  tasks_content: |
+    ## Quality Improvements (from AI assessment)
+
+    - [ ] Add performance requirements (HIGH)
+      - Profile update: <1s
+      - Avatar upload: <5s
+
+    - [ ] Specify avatar upload constraints (HIGH)
+      - Max size: 5MB
+      - Formats: JPG, PNG, WebP
+      - Dimensions: 512x512
+
+    - [ ] Define edit conflict resolution (MEDIUM)
+      - Strategy: Last-write-wins or optimistic locking
+
+validation:
+  - "Suggestions exported to tasks.md"
+  - "Tasks in markdown checklist format"
+  - "Each task labeled with priority (HIGH/MEDIUM/LOW)"
+  - "Tasks include specific details, not vague"
+  - "File created at correct path"
+  - "At least 3 tasks added"
+
+success_criteria:
+  - "Export completes without errors"
+  - "Tasks are actionable with clear details"
+  - "Priority labels match suggestion priorities"
+  - "Tasks integrate cleanly with existing tasks.md"
+  - "Can check off tasks as they're completed"
+---

package/src/skills/jira-sync/README.md

@@ -0,0 +1,328 @@
+# jira-sync Skill
+
+**Status**: To be developed
+**Priority**: Medium
+
+## Purpose
+
+Bidirectional sync between SpecWeave increments and JIRA (Atlassian)
+
+**Note**: This skill handles ONLY JIRA. For Azure DevOps, see `ado-sync` skill.
+
+## Features
+
+### Export to JIRA
+- Create JIRA issues from SpecWeave increments
+- Map spec.md user stories → JIRA Stories
+- Map tasks.md tasks → JIRA Sub-tasks
+- Create Epics if specified in spec.md
+- Set priorities, labels, components
+
+### Import from JIRA
+- Sync JIRA updates back to SpecWeave
+- Import existing JIRA issues as increments
+- Update status, assignees, comments
+
+### Bidirectional Sync
+- Keep status in sync (To Do, In Progress, Done)
+- Sync descriptions and acceptance criteria
+- Sync comments
+- Handle conflicts intelligently
+
+## JIRA-Specific Concepts
+
+### Mapping: SpecWeave → JIRA
+
+| SpecWeave | JIRA |
+|-----------|------|
+| spec.md (with Epic) | Epic |
+| spec.md User Story | Story |
+| tasks.md Task | Sub-task |
+| Acceptance Tests (spec.md) | Acceptance Criteria (Story) |
+| Acceptance Criteria (tasks.md) | Sub-task checklist |
+| Status: planned | To Do |
+| Status: in-progress | In Progress |
+| Status: completed | Done |
+
+### JIRA Structure Example
+
+**spec.md with JIRA structure**:
+```markdown
+---
+increment: 002-payment-processing
+status: planned
+structure: jira
+jira_epic: PROJ-123
+---
+
+## Epic: E-commerce Infrastructure
+**JIRA**: PROJ-123
+
+### Story: Subscribe to Plan
+**JIRA**: PROJ-124
+**Priority**: P1
+**Labels**: payments, stripe
+**Components**: Backend, Frontend
+
+**Description**:
+As a user, I want to subscribe to a monthly plan...
+
+**Acceptance Criteria**:
+- User can select plan
+- Payment processed
+- Subscription activated
+```
+
+**tasks.md creates Sub-tasks**:
+```markdown
+## Tasks for PROJ-124 (Subscribe to Plan)
+
+### Task T001: Create StripeService
+**JIRA**: PROJ-125 (Sub-task of PROJ-124)
+**Agent**: nodejs-backend
+
+**Description**: Create Stripe service class...
+
+**Acceptance Criteria**:
+- [ ] StripeService class exists
+- [ ] Unit tests passing
+```
+
+## Authentication
+
+**JIRA Cloud**:
+```yaml
+# .specweave/config.yaml
+jira_sync:
+  type: "cloud"
+  url: "https://your-org.atlassian.net"
+  email: "user@example.com"
+  api_token: "${JIRA_API_TOKEN}"  # From environment variable
+  project_key: "PROJ"
+```
+
+**JIRA Server/Data Center**:
+```yaml
+jira_sync:
+  type: "server"
+  url: "https://jira.your-company.com"
+  username: "user"
+  password: "${JIRA_PASSWORD}"  # From environment variable
+  project_key: "PROJ"
+```
+
+## Configuration
+
+```yaml
+# .specweave/config.yaml
+jira_sync:
+  enabled: false
+
+  # JIRA instance
+  url: "https://your-org.atlassian.net"
+  project_key: "PROJ"
+
+  # Authentication (use environment variables!)
+  email: "${JIRA_EMAIL}"
+  api_token: "${JIRA_API_TOKEN}"
+
+  # Sync settings
+  sync_direction: "bidirectional"  # export | import | bidirectional
+  sync_interval: 300  # seconds (5 minutes)
+
+  # What to sync
+  sync_status: true
+  sync_comments: true
+  sync_assignees: true
+  sync_attachments: false
+
+  # Issue mapping
+  epic_label: "epic"  # Custom field or label for epics
+
+  # Webhooks (for real-time sync)
+  webhook_enabled: true
+  webhook_secret: "${JIRA_WEBHOOK_SECRET}"
+```
+
+## Workflow
+
+### Export Workflow (SpecWeave → JIRA)
+
+```
+User: Creates increment in SpecWeave
+  .specweave/increments/0002-payment/
+    spec.md (with structure: jira)
+    tasks.md
+
+↓ jira-sync detects new increment
+
+Creates in JIRA:
+  Epic: PROJ-123 "E-commerce Infrastructure"
+    Story: PROJ-124 "Subscribe to Plan"
+      Sub-task: PROJ-125 "Create StripeService"
+      Sub-task: PROJ-126 "Create API endpoints"
+
+Links created:
+  spec.md → PROJ-124
+  tasks.md T001 → PROJ-125
+  tasks.md T002 → PROJ-126
+```
+
+### Import Workflow (JIRA → SpecWeave)
+
+```
+User: Updates JIRA issue status to "In Progress"
+
+↓ JIRA webhook triggers
+
+jira-sync:
+  Detects change to PROJ-124
+  Finds linked increment: 002-payment
+  Updates: .specweave/increments/0002-payment/spec.md
+    status: planned → in-progress
+```
+
+### Bidirectional Sync
+
+```
+User: Checks off task in tasks.md
+  - [x] T001: Create StripeService
+
+↓ jira-sync detects change
+
+Updates JIRA:
+  PROJ-125 status → Done
+
+User: Changes PROJ-124 to "Done" in JIRA
+
+↓ JIRA webhook triggers
+
+jira-sync updates SpecWeave:
+  .specweave/increments/0002-payment/spec.md
+    status: in-progress → completed
+```
+
+## API Integration
+
+### JIRA REST API Endpoints Used
+
+```typescript
+// Create Epic
+POST /rest/api/3/issue
+{
+  "fields": {
+    "project": { "key": "PROJ" },
+    "issuetype": { "name": "Epic" },
+    "summary": "E-commerce Infrastructure",
+    "customfield_10011": "epic-name"  // Epic Name field
+  }
+}
+
+// Create Story (linked to Epic)
+POST /rest/api/3/issue
+{
+  "fields": {
+    "project": { "key": "PROJ" },
+    "issuetype": { "name": "Story" },
+    "summary": "Subscribe to Plan",
+    "parent": { "key": "PROJ-123" }  // Link to Epic
+  }
+}
+
+// Create Sub-task
+POST /rest/api/3/issue
+{
+  "fields": {
+    "project": { "key": "PROJ" },
+    "issuetype": { "name": "Sub-task" },
+    "parent": { "key": "PROJ-124" },
+    "summary": "Create StripeService"
+  }
+}
+
+// Update status
+POST /rest/api/3/issue/{issueKey}/transitions
+{
+  "transition": { "id": "31" }  // "In Progress"
+}
+```
+
+## Webhooks
+
+### Setup JIRA Webhook
+
+1. Go to JIRA Settings → System → Webhooks
+2. Create webhook:
+   - URL: `https://your-app.com/api/webhooks/jira`
+   - Events: Issue created, updated, deleted
+   - Secret: Random string (store in JIRA_WEBHOOK_SECRET)
+
+### Webhook Handler
+
+```typescript
+// Receives JIRA webhook
+POST /api/webhooks/jira
+
+// jira-sync processes:
+1. Verify webhook signature
+2. Extract issue data
+3. Find linked SpecWeave increment
+4. Update spec.md or tasks.md
+5. Commit changes (optional)
+```
+
+## Conflict Resolution
+
+**Scenario**: Both SpecWeave and JIRA updated simultaneously
+
+**Strategy**:
+1. **Timestamp-based**: Latest change wins
+2. **User prompt**: Ask user which to keep
+3. **Merge**: Combine changes if possible
+
+**Example**:
+```
+SpecWeave: status → in-progress (10:00 AM)
+JIRA: status → done (10:05 AM)
+
+jira-sync:
+  Latest is JIRA (10:05 AM)
+  Update SpecWeave → done
+```
+
+## Error Handling
+
+**Common errors**:
+- JIRA API rate limits → Retry with exponential backoff
+- Authentication failed → Notify user, check credentials
+- Issue not found → Create if export, skip if import
+- Network errors → Queue for retry
+
+## Testing
+
+**Test scenarios**:
+1. Create increment → Creates JIRA issues
+2. Update JIRA → Updates SpecWeave
+3. Update SpecWeave → Updates JIRA
+4. Conflict resolution
+5. Webhook handling
+6. Error recovery
+
+## Integration with Other Skills
+
+- **task-builder**: Reads JIRA structure from spec.md
+- **increment-planner**: Can specify structure: jira
+
+## Future Enhancements
+
+- Support for JIRA sprints/iterations
+- Sync custom fields
+- Attachment sync
+- Advanced filtering (which issues to sync)
+- Bulk import from JIRA
+
+---
+
+**To implement**: See task in .specweave/increments/
+
+**See also**: `ado-sync` skill for Azure DevOps integration