specweave 0.18.0 → 0.20.0

package/plugins/specweave-jira/commands/specweave-jira-sync-epic.md

@@ -1,267 +0,0 @@
----
-name: specweave-jira-sync-epic
-description: Sync SpecWeave Epic folder to JIRA (Epic + Stories with Epic Link). Implements Universal Hierarchy architecture - Epic → JIRA Epic, Increments → Stories.
----
-
-# Sync Epic to JIRA (Universal Hierarchy)
-
-**Architecture**: Hierarchical sync using Epic folder structure
-
-- **Epic (FS-001)** → **JIRA Epic**
-- **Increment (0001-core-framework)** → **JIRA Story** (Epic Link field)
-
-## Usage
-
-```bash
-/specweave-jira:sync-epic <epic-id> [--project <project-key>]
-```
-
-## What It Does
-
-**Hierarchical Sync Process**:
-
-1. **Load Epic folder** from `.specweave/docs/internal/specs/FS-XXX-name/`
-2. **Parse Epic README.md** to get Epic metadata (title, increments, status)
-3. **Create or update JIRA Epic**:
-   - Summary: `[FS-001] Epic Title`
-   - Description: Epic overview + progress stats
-   - Priority: Mapped from P0→Highest, P1→High, etc.
-   - Labels: `epic-sync`, `fs-001`
-4. **Sync each increment as JIRA Story**:
-   - Summary: `[INC-0001-core-framework] Title`
-   - Description: Increment overview
-   - Epic Link: Links to Epic via `epicKey` field
-   - Labels: `increment`, `epic-sync`
-5. **Update frontmatter** in Epic README.md and increment files
-
-## Examples
-
-### Sync Epic FS-001 (Core Framework Architecture)
-
-```bash
-/specweave-jira:sync-epic FS-001 --project SPEC
-```
-
-**Output**:
-```
-🔄 Syncing Epic FS-001 to JIRA...
-   📦 Epic: Core Framework Architecture
-   📊 Increments: 4
-   🚀 Creating JIRA Epic...
-   ✅ Created Epic SPEC-100
-
-   📝 Syncing 4 increments...
-   ✅ Created Story SPEC-101 for 0001-core-framework
-   ✅ Created Story SPEC-102 for 0002-core-enhancements
-   ✅ Created Story SPEC-103 for 0004-plugin-architecture
-   ✅ Created Story SPEC-104 for 0005-cross-platform-cli
-
-✅ Epic sync complete!
-   Epic: https://mycompany.atlassian.net/browse/SPEC-100
-   Stories created: 4
-   Stories updated: 0
-```
-
-### Sync Epic with short ID
-
-```bash
-/specweave-jira:sync-epic 031 --project SPEC
-```
-
-### Re-sync Epic (updates existing)
-
-```bash
-/specweave-jira:sync-epic FS-001 --project SPEC
-```
-
-**Output**:
-```
-🔄 Syncing Epic FS-001 to JIRA...
-   ♻️  Updating existing Epic SPEC-100...
-   ✅ Updated Epic SPEC-100
-
-   📝 Syncing 4 increments...
-   ♻️  Updated Story SPEC-101 for 0001-core-framework
-   ♻️  Updated Story SPEC-102 for 0002-core-enhancements
-   ♻️  Updated Story SPEC-103 for 0004-plugin-architecture
-   ♻️  Updated Story SPEC-104 for 0005-cross-platform-cli
-
-✅ Epic sync complete!
-   Epic: https://mycompany.atlassian.net/browse/SPEC-100
-   Stories created: 0
-   Stories updated: 4
-```
-
-## Arguments
-
-- `<epic-id>` - Epic ID (e.g., `FS-001` or just `001`)
-- `--project <key>` - JIRA project key (e.g., `SPEC`, `PROJ`, `DEV`)
-
-## What Gets Created
-
-### JIRA Epic (Epic-level)
-
-```
-Key: SPEC-100
-Summary: [FS-001] Core Framework Architecture
-
-Description:
-  Epic: Core Framework Architecture
-
-  Progress: 4/4 increments (100%)
-
-  Priority: P0
-  Status: complete
-
-Labels: epic-sync, fs-001
-Priority: Highest (P0 → Highest)
-```
-
-### JIRA Story (Increment-level)
-
-```
-Key: SPEC-101
-Summary: [INC-0001-core-framework] Core Framework
-
-Description:
-  Foundation framework with CLI, plugin system, and agent architecture...
-
-  ---
-
-  **Increment**: 0001-core-framework
-  **Epic**: SPEC-100
-
-  🤖 Auto-created by SpecWeave Epic Sync
-
-Epic Link: SPEC-100 (linked via Epic Link field)
-Labels: increment, epic-sync
-```
-
-## Frontmatter Updates
-
-### Epic README.md (after sync)
-
-```yaml
----
-id: FS-001
-title: "Core Framework Architecture"
-external_tools:
-  jira:
-    type: epic
-    key: SPEC-100                       # ← Added
-    url: https://mycompany.atlassian.net/browse/SPEC-100  # ← Added
-increments:
-  - id: 0001-core-framework
-    external:
-      jira: SPEC-101                    # ← Added
-  - id: 0002-core-enhancements
-    external:
-      jira: SPEC-102                    # ← Added
----
-```
-
-### Increment file (0001-core-framework.md)
-
-```yaml
----
-id: 0001-core-framework
-epic: FS-001
-external:
-  jira:
-    story: SPEC-101                     # ← Added
-    url: https://mycompany.atlassian.net/browse/SPEC-101  # ← Added
----
-```
-
-## Benefits
-
-✅ **Hierarchical tracking**: JIRA Epics group related Stories
-✅ **Epic-level progress**: See completion in Epic details
-✅ **Automatic linking**: Epic Link field links Stories to Epic
-✅ **Idempotent**: Safe to re-run (updates existing Epic/Stories)
-✅ **Brownfield-ready**: Links existing JIRA Epics/Stories
-
-## Requirements
-
-1. **JIRA credentials** in `.env`:
-   ```
-   JIRA_DOMAIN=mycompany.atlassian.net
-   JIRA_EMAIL=user@mycompany.com
-   JIRA_API_TOKEN=your-api-token
-   ```
-2. **Project exists** in JIRA
-3. **Write access** to project (for creating Epics/Stories)
-4. **Epic folder exists** at `.specweave/docs/internal/specs/FS-XXX-name/`
-
-## Architecture: Why Epic Link?
-
-**JIRA's Hierarchy**:
-- JIRA Epics = Top-level grouping
-- JIRA Stories = Implementation work
-- Epic Link field = Links Stories to Epic
-
-**Comparison with GitHub/ADO**:
-- GitHub: Epic → Milestone, Increment → Issue (Milestone link)
-- JIRA: Epic → Epic, Increment → Story (Epic Link field)
-- ADO: Epic → Feature, Increment → User Story (Parent link)
-
-All three implement the same Universal Hierarchy, just with different fields/terminology.
-
-## Priority Mapping
-
-| SpecWeave | JIRA |
-|-----------|------|
-| P0 | Highest |
-| P1 | High |
-| P2 | Medium |
-| P3 | Low |
-
-## Troubleshooting
-
-**"Epic FS-001 not found"**:
-- Check Epic folder exists: `ls .specweave/docs/internal/specs/`
-- Verify Epic ID format: `FS-001-epic-name/`
-
-**"Epic README.md missing YAML frontmatter"**:
-- Ensure Epic was migrated with `migrate-to-epic-folders.ts`
-- Frontmatter must start with `---` on line 1
-
-**"Failed to create JIRA Epic"**:
-- Check credentials: `echo $JIRA_API_TOKEN`
-- Verify project exists in JIRA
-- Check write permissions
-
-**"Epic Link field not found"**:
-- Some JIRA instances use custom field for Epic Link
-- Check with JIRA admin for custom field ID
-- May need configuration update
-
-## Related Commands
-
-- `/specweave-github:sync-epic` - Sync to GitHub Milestone + Issues
-- `/specweave-ado:sync-epic` - Sync to ADO Feature + User Stories
-- `/specweave-jira:sync-spec` - OLD (flat spec → epic) - DEPRECATED
-
-## Implementation
-
-**File**: `plugins/specweave-jira/lib/jira-epic-sync.ts`
-
-**Core Class**: `JiraEpicSync`
-
-**Methods**:
-- `syncEpicToJira(epicId)` - Main sync logic
-- `createEpic(epic)` - Create JIRA Epic
-- `updateEpic(key, epic)` - Update existing Epic
-- `createStory(increment, epicKey)` - Create JIRA Story
-- `updateStory(key, increment, epicKey)` - Update existing Story
-- `updateEpicReadme(path, jira)` - Update frontmatter
-- `updateIncrementExternalLink(...)` - Update increment frontmatter
-
-## Next Steps
-
-After syncing Epic to JIRA:
-
-1. **View Epic**: Open in JIRA browser
-2. **List Stories**: Filter by Epic Link field
-3. **Track completion**: JIRA shows Epic progress automatically
-4. **Link to Sprint**: Drag Stories into Sprint planning

package/plugins/specweave-jira/commands/specweave-jira-sync-spec.md

@@ -1,240 +0,0 @@
----
-name: specweave-jira-sync-spec
-description: Sync SpecWeave spec to Jira Epic (bidirectional). Use when syncing .specweave/docs/internal/specs/spec-*.md files with Jira Epics for permanent feature tracking.
----
-
-# Sync Spec to Jira Epic
-
-**CORRECT ARCHITECTURE**: This command syncs `.specweave/docs/internal/specs/spec-*.md` files (PERMANENT living docs) to Jira Epics, NOT increments to issues.
-
-## Usage
-
-```bash
-/specweave-jira:sync-spec <spec-id> [--direction <to-jira|from-jira|bidirectional>]
-```
-
-## What It Does
-
-**Architecture**:
-- **Spec → Jira Epic** (not increment → issue!)
-- **User Story → Jira Story** (subtask of epic)
-- **Acceptance Criteria → Checklist** (in story description)
-
-**Sync Process**:
-
-1. **Load spec** from `.specweave/docs/internal/specs/spec-{id}.md`
-2. **Load Jira configuration** from `.env` (domain, email, API token, project key)
-3. **Create or update Jira Epic**:
-   - Summary: `[SPEC-001] Feature Title`
-   - Description: Spec overview + progress
-   - Status: Matches spec status
-4. **Sync user stories as Jira Stories**:
-   - Create stories for new user stories
-   - Update existing stories
-   - Transition stories based on user story status
-5. **Link spec to epic** (update frontmatter)
-
-## Examples
-
-### Sync spec to Jira (create or update)
-
-```bash
-/specweave-jira:sync-spec spec-001
-```
-
-**Output**:
-```
-🔄 Syncing spec spec-001 to Jira Epic...
-   Creating new Jira Epic...
-   ✅ Created Jira Epic SPEC-1: https://company.atlassian.net/browse/SPEC-1
-   Syncing 35 user stories...
-   ✅ Created US-001 → Story SPEC-2
-   ✅ Created US-002 → Story SPEC-3
-   ...
-✅ Sync complete!
-   Created: 35 user stories
-   Jira Epic: https://company.atlassian.net/browse/SPEC-1
-```
-
-### Sync FROM Jira to spec (bidirectional)
-
-```bash
-/specweave-jira:sync-spec spec-001 --direction from-jira
-```
-
-**Output**:
-```
-🔄 Syncing FROM Jira to spec spec-001...
-   Fetching Jira Epic SPEC-1...
-   ⚠️  Detected 3 conflict(s)
-   🔄 Resolving: US-002 marked Done in Jira (Jira wins)
-   🔄 Resolving: US-005 marked In Progress in Jira (Jira wins)
-✅ Sync FROM Jira complete!
-   Updated: 3 user stories
-```
-
-## Arguments
-
-- `<spec-id>` - Spec ID (e.g., `spec-001` or just `001`)
-- `--direction <mode>` - Sync direction (default: `to-jira`)
-  - `to-jira` - Push local spec to Jira
-  - `from-jira` - Pull Jira state to spec
-  - `bidirectional` - Sync both ways (conflict resolution)
-
-## Configuration
-
-**Required `.env` variables**:
-
-```bash
-# Jira Configuration
-JIRA_DOMAIN=company.atlassian.net
-JIRA_EMAIL=your-email@company.com
-JIRA_API_TOKEN=your_api_token_here
-JIRA_PROJECT_KEY=SPEC
-```
-
-**How to get API token**:
-1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
-2. Click "Create API token"
-3. Copy token to `.env`
-
-## Conflict Resolution
-
-When syncing FROM Jira, conflicts are resolved as follows:
-
-**Jira wins** (default):
-- User story status changes → update spec
-- Acceptance criteria status → update spec
-- Story completion → mark user story done
-
-**Local wins** (future):
-- Spec changes take precedence
-- Push to Jira
-
-## Requirements
-
-1. **Jira account** with API access
-2. **Jira API token** (from https://id.atlassian.com/manage-profile/security/api-tokens)
-3. **Project permissions** (create epics, create stories)
-4. **Spec file exists** at `.specweave/docs/internal/specs/spec-{id}.md`
-
-## What Gets Synced
-
-### Spec → Jira Epic
-
-- ✅ Summary: `[SPEC-001] Feature Area Title`
-- ✅ Description: Overview + progress stats (Jira wiki markup)
-- ✅ Labels: `spec:spec-001`, `priority:P1`
-- ✅ Status: To Do/In Progress/Done based on spec
-
-### User Story → Jira Story
-
-- ✅ Summary: `[US-001] As a user, I want...`
-- ✅ Description: User story + acceptance criteria checklist
-- ✅ Labels: `user-story`, `spec:spec-001`, `priority:P1`
-- ✅ Epic Link: Links story to epic
-- ✅ Status: To Do (todo) / In Progress (in-progress) / Done (done)
-
-### Acceptance Criteria → Checklist
-
-```
-h2. Acceptance Criteria
-
-* (/) User can log in with email/password
-* (x) Invalid credentials show error message
-* (x) Account locks after 5 failed attempts
-```
-
-*Note*: Jira uses `(/)` for checked, `(x)` for unchecked.
-
-## Architecture
-
-**Why This Architecture?**
-
-✅ **Permanent tracking**: Specs never deleted, Jira links remain valid
-✅ **Feature-level granularity**: One Jira Epic per feature (not per increment)
-✅ **PM-friendly**: Stakeholders see progress in Jira board
-✅ **Brownfield-ready**: Existing Jira epics map to specs
-
-**What's WRONG?**
-
-❌ Increment → Jira Issue (increments are temporary!)
-❌ Tasks → Jira Issues (too granular, implementation details)
-❌ Multiple epics per feature (split across increments)
-
-## Metadata
-
-After sync, spec frontmatter is updated:
-
-```yaml
----
-id: spec-001
-title: Core Framework Architecture
-status: in-progress
-priority: P0
-externalLinks:
-  jira:
-    epicKey: SPEC-1
-    epicUrl: https://company.atlassian.net/browse/SPEC-1
-    syncedAt: "2025-11-10T12:00:00Z"
-    projectKey: SPEC
-    domain: company.atlassian.net
----
-```
-
-## Troubleshooting
-
-**"Jira API authentication failed"**:
-- Check `.env` has correct `JIRA_DOMAIN`, `JIRA_EMAIL`, `JIRA_API_TOKEN`
-- Verify API token is valid (not expired)
-- Test authentication: `curl -u email:token https://company.atlassian.net/rest/api/3/myself`
-
-**"Spec not found"**:
-- Check spec exists: `ls .specweave/docs/internal/specs/`
-- Use correct ID: `spec-001` or `001`
-
-**"Cannot create epic"**:
-- Ensure you have permissions to create epics in the project
-- Check project key is correct in `.env`
-
-**"Epic Link field not found"**:
-- Epic Link field ID varies by Jira configuration
-- Default: `customfield_10014`
-- Find your field: Go to Jira → Settings → Issues → Custom fields → Find "Epic Link"
-- Update code if needed
-
-**"No user stories to sync"**:
-- Add user stories to spec.md:
-  ```markdown
-  **US-001**: As a user, I want...
-  - [ ] **AC-001-01**: Acceptance criteria 1
-  ```
-
-## Related
-
-- `/specweave-github:sync-spec` - Sync to GitHub Project
-- `/specweave-ado:sync-spec` - Sync to Azure DevOps Feature
-- `/specweave:sync-docs` - Sync living docs from increments to specs
-
-## Implementation
-
-**File**: `plugins/specweave-jira/lib/jira-spec-sync.ts`
-
-**Core Class**: `JiraSpecSync`
-
-**Methods**:
-- `syncSpecToJira(specId)` - Push to Jira
-- `syncFromJira(specId)` - Pull from Jira
-- `detectConflicts(spec, epic)` - Compare states
-- `resolveConflicts(spec, conflicts)` - Apply resolution strategy
-
-## Jira API Reference
-
-**Endpoints used**:
-- `POST /rest/api/3/issue` - Create epic/story
-- `PUT /rest/api/3/issue/{key}` - Update epic/story
-- `GET /rest/api/3/issue/{key}` - Fetch epic/story
-- `GET /rest/api/3/search?jql=...` - Search for stories
-- `POST /rest/api/3/issue/{key}/transitions` - Transition story status
-
-**Authentication**: Basic auth with email + API token