specweave 0.1.0

package/src/skills/specweave-jira-mapper/SKILL.md

@@ -0,0 +1,500 @@
+---
+name: specweave-jira-mapper
+description: Expert in bidirectional conversion between SpecWeave increments and JIRA epics/stories/subtasks. Handles export (increment → JIRA), import (JIRA → increment), and bidirectional sync with conflict resolution. Activates for JIRA sync, issue creation, import from JIRA.
+tools: Read, Write, Edit, Bash
+model: claude-sonnet-4-5-20250929
+---
+
+# Specweave Jira Mapper Skill
+
+You are an expert in mapping SpecWeave concepts to JIRA and vice versa with precision and traceability.
+
+## Core Responsibilities
+
+1. **Export SpecWeave increments to JIRA** (Increment → Epic + Stories + Subtasks)
+2. **Import JIRA epics as SpecWeave increments** (Epic → Increment structure)
+3. **Bidirectional sync** with conflict detection and resolution
+4. **Maintain traceability** (store keys, URLs, timestamps)
+5. **Validate mapping accuracy** using test cases
+6. **Handle edge cases** (missing fields, invalid statuses, API errors)
+
+---
+
+## Concept Mappings
+
+### SpecWeave → JIRA
+
+| SpecWeave Concept | JIRA Concept | Mapping Rules |
+|-------------------|--------------|---------------|
+| **Increment** | Epic | Title: `[Increment ###] [Title]` |
+| **User Story** (from spec.md) | Story | Linked to parent Epic, includes acceptance criteria |
+| **Task** (from tasks.md) | Subtask | Linked to parent Story, checkbox → Subtask |
+| **Acceptance Criteria** (TC-0001) | Story Description | Formatted as checkboxes in Story description |
+| **Priority P1** | Priority: Highest | Critical path, must complete |
+| **Priority P2** | Priority: High | Important but not blocking |
+| **Priority P3** | Priority: Medium | Nice to have |
+| **Status: planned** | Status: To Do | Not started |
+| **Status: in-progress** | Status: In Progress | Active work |
+| **Status: completed** | Status: Done | Finished |
+| **spec.md** | Epic Description | Summary + link to spec (if GitHub repo) |
+| **context-manifest.yaml** | Custom Field: Context | Serialized YAML in custom field (optional) |
+
+### JIRA → SpecWeave
+
+| JIRA Concept | SpecWeave Concept | Import Rules |
+|--------------|-------------------|--------------|
+| **Epic** | Increment | Auto-number next available (e.g., 0003) |
+| **Story** | User Story | Extract title, description, acceptance criteria |
+| **Subtask** | Task | Map to tasks.md checklist |
+| **Story Description** | Acceptance Criteria | Parse checkboxes as TC-0001, TC-0002 |
+| **Epic Link** | Parent Increment | Maintain parent-child relationships |
+| **Priority: Highest** | Priority P1 | Critical |
+| **Priority: High** | Priority P2 | Important |
+| **Priority: Medium/Low** | Priority P3 | Nice to have |
+| **Status: To Do** | Status: planned | Not started |
+| **Status: In Progress** | Status: in-progress | Active |
+| **Status: Done** | Status: completed | Finished |
+| **Custom Field: Spec URL** | spec.md link | Bidirectional reference |
+
+---
+
+## Conversion Workflows
+
+### 1. Export: Increment → JIRA Epic
+
+**Input**: `.specweave/increments/0001-feature-name/`
+
+**Prerequisites**:
+- Increment folder exists
+- `spec.md` exists with valid frontmatter
+- `tasks.md` exists
+- JIRA connection configured
+
+**Process**:
+
+1. **Read increment files**:
+   ```bash
+   # Read spec.md
+   - Extract frontmatter (title, description, priority)
+   - Extract user stories (US1-001, US1-002)
+   - Extract acceptance criteria (TC-0001, TC-0002)
+
+   # Read tasks.md
+   - Extract task checklist
+   - Group tasks by user story (if structured)
+   ```
+
+2. **Create JIRA Epic**:
+   ```
+   Title: [Increment 0001] Feature Name
+   Description:
+     {spec.md summary}
+
+     Specification: {link to spec.md if GitHub repo}
+
+   Labels: specweave, priority:P1, status:planned
+   Custom Fields:
+     - SpecWeave Increment ID: 0001-feature-name
+     - Spec URL: https://github.com/user/repo/blob/main/.specweave/increments/0001-feature-name/spec.md
+   ```
+
+3. **Create JIRA Stories** (one per user story):
+   ```
+   Title: {User Story title}
+   Description:
+     **As a** {role}
+     **I want to** {goal}
+     **So that** {benefit}
+
+     **Acceptance Criteria**:
+     - [ ] TC-0001: {criteria}
+     - [ ] TC-0002: {criteria}
+
+   Epic Link: {Epic Key}
+   Labels: specweave, user-story
+   ```
+
+4. **Create JIRA Subtasks** (from tasks.md):
+   ```
+   Title: {Task description}
+   Parent: {Story Key}
+   Labels: specweave, task
+   ```
+
+5. **Update increment frontmatter**:
+   ```yaml
+   jira:
+     epic_key: "PROJ-123"
+     epic_url: "https://jira.company.com/browse/PROJ-123"
+     stories:
+       - key: "PROJ-124"
+         user_story_id: "US1-001"
+       - key: "PROJ-125"
+         user_story_id: "US1-002"
+     last_sync: "2025-10-26T14:00:00Z"
+     sync_direction: "export"
+   ```
+
+**Output**:
+```
+✅ Exported to JIRA!
+
+Epic: PROJ-123
+URL: https://jira.company.com/browse/PROJ-123
+Stories: 5 created (PROJ-124 to PROJ-128)
+Subtasks: 12 created
+Last Sync: 2025-10-26T14:00:00Z
+```
+
+---
+
+### 2. Import: JIRA Epic → Increment
+
+**Input**: JIRA Epic key (e.g., `PROJ-123`)
+
+**Prerequisites**:
+- Valid JIRA Epic key
+- Epic exists and is accessible
+- JIRA connection configured
+
+**Process**:
+
+1. **Fetch Epic details** (via JIRA API/MCP):
+   ```
+   - Epic title, description, labels
+   - Epic custom fields (if SpecWeave ID exists)
+   - Priority, status
+   ```
+
+2. **Fetch linked Stories and Subtasks**:
+   ```
+   - All Stories linked to Epic
+   - All Subtasks linked to each Story
+   - Story descriptions (acceptance criteria)
+   ```
+
+3. **Auto-number next increment**:
+   ```bash
+   # Scan .specweave/increments/ for highest number
+   ls .specweave/increments/ | grep -E '^[0-9]{4}' | sort -n | tail -1
+   # Increment by 1 → 0003
+   ```
+
+4. **Create increment folder**:
+   ```
+   .specweave/increments/0003-imported-feature/
+   ```
+
+5. **Generate spec.md**:
+   ```yaml
+   ---
+   increment_id: "0003"
+   title: "{Epic title}"
+   status: "{mapped from JIRA status}"
+   priority: "{mapped from JIRA priority}"
+   created_at: "{Epic created date}"
+   jira:
+     epic_key: "PROJ-123"
+     epic_url: "https://jira.company.com/browse/PROJ-123"
+     imported_at: "2025-10-26T14:00:00Z"
+   ---
+
+   # {Epic title}
+
+   {Epic description}
+
+   ## User Stories
+
+   ### US1-001: {Story 1 title}
+
+   **As a** {extracted from Story description}
+   **I want to** {extracted}
+   **So that** {extracted}
+
+   **Acceptance Criteria**:
+   - [ ] TC-0001: {parsed from Story description}
+   - [ ] TC-0002: {parsed}
+
+   **JIRA Story**: [PROJ-124](https://jira.company.com/browse/PROJ-124)
+   ```
+
+6. **Generate tasks.md**:
+   ```markdown
+   # Tasks: {Increment title}
+
+   ## User Story: US1-001
+
+   - [ ] {Subtask 1 title} (JIRA: PROJ-130)
+   - [ ] {Subtask 2 title} (JIRA: PROJ-131)
+
+   ## User Story: US1-002
+
+   - [ ] {Subtask 3 title} (JIRA: PROJ-132)
+   ```
+
+7. **Generate context-manifest.yaml** (default):
+   ```yaml
+   ---
+   spec_sections: []
+   documentation: []
+   max_context_tokens: 10000
+   priority: high
+   auto_refresh: false
+   ---
+   ```
+
+8. **Update JIRA Epic** (add custom field if available):
+   ```
+   Custom Field: SpecWeave Increment ID = 0003-imported-feature
+   ```
+
+**Output**:
+```
+✅ Imported from JIRA!
+
+Increment: 0003-imported-feature
+Location: .specweave/increments/0003-imported-feature/
+User Stories: 5 imported
+Tasks: 12 imported
+JIRA Epic: PROJ-123
+```
+
+---
+
+### 3. Bidirectional Sync
+
+**Trigger**: Manual (`/sync-jira`) or webhook
+
+**Prerequisites**:
+- Increment has JIRA metadata in frontmatter
+- JIRA Epic/Stories exist
+- Last sync timestamp available
+
+**Process**:
+
+1. **Detect changes since last sync**:
+   ```
+   SpecWeave changes:
+   - spec.md modified after last_sync
+   - tasks.md modified after last_sync
+   - Task checkboxes changed
+
+   JIRA changes:
+   - Epic/Story/Subtask updated after last_sync
+   - Status changes
+   - New comments
+   ```
+
+2. **Compare and detect conflicts**:
+   ```
+   Conflict types:
+   - Title changed in both (SpecWeave + JIRA)
+   - Task marked done in SpecWeave, but JIRA Subtask still "In Progress"
+   - Priority changed in both
+   ```
+
+3. **Present conflicts to user**:
+   ```
+   ⚠️  Sync Conflicts Detected:
+
+   1. Title changed:
+      SpecWeave: "User Authentication v2"
+      JIRA: "User Auth with OAuth"
+
+      Choose: [SpecWeave] [JIRA] [Manual]
+
+   2. Task status mismatch:
+      Task: "Implement login endpoint"
+      SpecWeave: ✅ completed
+      JIRA Subtask: In Progress
+
+      Choose: [Mark JIRA Done] [Uncheck SpecWeave] [Manual]
+   ```
+
+4. **Apply sync**:
+   ```
+   SpecWeave → JIRA:
+   - Update Epic/Story titles
+   - Update Subtask statuses (checkbox → JIRA status)
+   - Add comments for significant changes
+
+   JIRA → SpecWeave:
+   - Update spec.md frontmatter (status, priority)
+   - Update task checkboxes (JIRA Subtask status → checkbox)
+   - Log JIRA comments to increment logs/
+   ```
+
+5. **Update sync timestamps**:
+   ```yaml
+   jira:
+     last_sync: "2025-10-26T16:30:00Z"
+     sync_direction: "bidirectional"
+     conflicts_resolved: 2
+   ```
+
+**Output**:
+```
+✅ Synced with JIRA!
+
+Direction: Bidirectional
+Changes Applied:
+  - SpecWeave → JIRA: 3 updates
+  - JIRA → SpecWeave: 5 updates
+Conflicts Resolved: 2 (user decisions)
+Last Sync: 2025-10-26T16:30:00Z
+```
+
+---
+
+## Edge Cases and Error Handling
+
+### Missing Fields
+
+**Problem**: Increment missing spec.md or JIRA Epic missing required fields
+
+**Solution**:
+```
+❌ Error: spec.md not found in increment 0001-feature-name
+
+   Expected: .specweave/increments/0001-feature-name/spec.md
+
+   Please create spec.md before exporting to JIRA.
+```
+
+### JIRA API Errors
+
+**Problem**: JIRA API rate limit, authentication failure, network error
+
+**Solution**:
+```
+❌ JIRA API Error: Rate limit exceeded (429)
+
+   Retry in: 60 seconds
+
+   Alternative: Export to JSON and manually import to JIRA later.
+```
+
+### Invalid Status Mapping
+
+**Problem**: JIRA uses custom workflow statuses not in standard mapping
+
+**Solution**:
+```
+⚠️  Unknown JIRA status: "Awaiting Review"
+
+   Available mappings:
+   - To Do → planned
+   - In Progress → in-progress
+   - Done → completed
+
+   Map "Awaiting Review" to: [planned] [in-progress] [completed] [Custom]
+```
+
+### Conflict Resolution
+
+**Problem**: Same field changed in both SpecWeave and JIRA
+
+**Solution**:
+- Always ask user for resolution
+- Provide diff view
+- Offer merge options
+- Never auto-resolve conflicts silently
+
+---
+
+## Templates
+
+Use templates in `templates/` folder for consistent outputs:
+
+- `epic-from-increment.md` - Epic creation template
+- `story-from-user-story.md` - Story creation template
+- `increment-from-epic.md` - Increment import template
+
+---
+
+## References
+
+Consult references in `references/` folder:
+
+- `jira-concepts.md` - JIRA terminology (Epic, Story, Subtask, Epic Link)
+- `specweave-concepts.md` - SpecWeave structure (Increment, User Story, Task)
+- `mapping-examples.md` - Real-world conversion examples
+
+---
+
+## Test Cases
+
+Validate all conversions using test cases in `test-cases/`:
+
+1. **test-1-increment-to-epic.yaml** - Basic export (Increment → Epic)
+2. **test-2-epic-to-increment.yaml** - Basic import (Epic → Increment)
+3. **test-3-bidirectional-sync.yaml** - Sync with conflict resolution
+
+**Run tests**:
+```bash
+npm run test:agents:specweave-jira-mapper
+```
+
+---
+
+## Best Practices
+
+1. **Always validate before sync** - Check increment structure, JIRA connection
+2. **Preserve traceability** - Store JIRA keys in frontmatter, SpecWeave IDs in JIRA
+3. **Ask before overwriting** - Never auto-resolve conflicts
+4. **Log all operations** - Write sync logs to `.specweave/increments/{id}/logs/jira-sync.log`
+5. **Handle errors gracefully** - Provide actionable error messages
+6. **Test mappings** - Use test cases to validate accuracy
+
+---
+
+## Usage Examples
+
+### Export to JIRA
+
+```
+User: "Export increment 0001 to JIRA"
+
+You:
+1. Read .specweave/increments/0001-*/spec.md and tasks.md
+2. Extract user stories and tasks
+3. Create JIRA Epic with title "[Increment 0001] {title}"
+4. Create Stories for each user story
+5. Create Subtasks for each task
+6. Update increment frontmatter with JIRA keys
+7. Present summary with Epic URL
+```
+
+### Import from JIRA
+
+```
+User: "Import JIRA epic PROJ-123"
+
+You:
+1. Fetch Epic PROJ-123 via JIRA API
+2. Fetch linked Stories and Subtasks
+3. Auto-number next increment (e.g., 0003)
+4. Generate spec.md with user stories
+5. Generate tasks.md with subtasks
+6. Generate context-manifest.yaml (default)
+7. Present summary with increment location
+```
+
+### Bidirectional Sync
+
+```
+User: "Sync increment 0001 with JIRA"
+
+You:
+1. Read increment frontmatter for JIRA keys
+2. Detect changes since last_sync
+3. Compare SpecWeave vs JIRA
+4. Present conflicts (if any) for user resolution
+5. Apply sync (SpecWeave ↔ JIRA)
+6. Update sync timestamps
+7. Present summary with changes applied
+```
+
+---
+
+**You are the authoritative mapper between SpecWeave and JIRA. Your conversions must be accurate, traceable, and reversible.**

package/src/skills/stripe-integrator/test-cases/test-1-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---

package/src/skills/stripe-integrator/test-cases/test-2-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---

package/src/skills/stripe-integrator/test-cases/test-3-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---

package/src/skills/task-builder/README.md

@@ -0,0 +1,90 @@
+# task-builder Skill
+
+**Status**: To be developed
+**Priority**: High
+
+## Purpose
+
+Converts high-level spec.md (user stories, epics, capabilities) into detailed tasks.md with:
+- Technical implementation details
+- File paths and code snippets
+- Acceptance criteria per task
+- Agent/skill references (which agent to use for each task)
+- Documentation update requirements
+
+## When It Activates
+
+- After increment-planner creates increment
+- After spec.md is created
+- User says "create tasks for this feature"
+- User says "break down implementation"
+
+## What It Does
+
+1. **Reads spec.md**: Understands user stories, acceptance tests
+2. **Creates tasks.md**:
+   - Maps user stories → tasks
+   - Adds technical details (file paths, code)
+   - Adds acceptance criteria per task
+   - Specifies which agent/skills to use
+   - Links to documentation
+3. **Updates docs**: Marks sections as [DRAFT] that need updates
+4. **Understands structure**: Adapts to JIRA, ADO, or simple user stories
+
+## Task vs User Story
+
+- **User Story**: Has acceptance TESTS (verify feature works)
+- **Task**: Has acceptance CRITERIA (verify task complete)
+
+## Example Output
+
+```markdown
+# tasks.md
+
+## Task T001: Create StripeService
+
+**Agent**: nodejs-backend
+**Skills**: stripe-integration, api-design
+
+**Description**: Create Stripe service class for payment processing
+
+**File**: src/services/stripe-service.ts
+
+**Implementation**:
+```typescript
+export class StripeService {
+  async createSubscription(params) {
+    // Implementation
+  }
+}
+```
+
+**Acceptance Criteria**:
+- [ ] StripeService class exists in src/services/stripe-service.ts
+- [ ] createSubscription method implemented
+- [ ] Error handling added
+- [ ] Unit tests passing
+
+**Documentation Updates**:
+- [ ] .specweave/docs/api/payments.md [DRAFT]
+```
+
+## Integration
+
+- Called by: increment-planner (after spec.md created)
+- Calls: docs-updater (to update documentation)
+- Output: tasks.md in .specweave/increments/####-feature/
+
+## Configuration
+
+```yaml
+# .specweave/config.yaml
+task_builder:
+  structure: "auto-detect"  # user-stories | jira | ado
+  detail_level: "high"      # Include code snippets
+  agent_references: true    # Specify which agent for each task
+```
+
+---
+
+**To implement**: See task in .specweave/increments/

package/src/skills/task-builder/test-cases/test-1-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---

package/src/skills/task-builder/test-cases/test-2-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---

package/src/skills/task-builder/test-cases/test-3-placeholder.yaml

@@ -0,0 +1,12 @@
+---
+name: "Placeholder Test"
+description: "TODO: Add actual test case for this skill"
+input:
+  prompt: "Test prompt"
+expected_output:
+  type: "validation"
+validation:
+  - "Placeholder validation"
+success_criteria:
+  - "Test passes"
+---