specweave 0.12.0 → 0.12.2

package/plugins/specweave-github/skills/github-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: github-sync
-description: Bidirectional synchronization between SpecWeave increments and GitHub Issues (two-way sync by default). Creates issues from increments, tracks progress via comments, updates increment status from issue state, syncs changes in both directions automatically. Activates for GitHub sync, issue creation, increment tracking, GitHub integration, issue management, sync to GitHub, bidirectional sync.
+description: Bidirectional synchronization between SpecWeave increments and GitHub Issues (two-way sync by default). Activates ONLY when user asks questions about GitHub integration or needs help configuring GitHub sync. Does NOT activate for slash commands. For syncing, use /specweave-github:sync command instead.
 ---
 
 # GitHub Sync - Bidirectional Increment ↔ Issue Synchronization
@@ -9,14 +9,22 @@ description: Bidirectional synchronization between SpecWeave increments and GitH
 
 **Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
 
-**When to Use**:
-- Creating new increments (auto-create GitHub issue)
-- Syncing increment progress to GitHub (comments with task completion %)
-- Closing increments (auto-close GitHub issue)
-- Importing GitHub issues as increments
-- Manual sync operations
+**⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about GitHub sync. For actual syncing, users should use the `/specweave-github:sync` command directly. This skill should NOT auto-activate when the command is being invoked.
 
-**Integration**: Works with `/specweave:github:sync` command
+## When to Activate
+
+✅ **Do activate when**:
+- User asks: "How do I set up GitHub sync?"
+- User asks: "What GitHub credentials do I need?"
+- User asks: "How does the GitHub integration work?"
+- User needs help configuring GitHub integration
+
+❌ **Do NOT activate when**:
+- User invokes `/specweave-github:sync` command (command handles it)
+- Command is already running (avoid duplicate invocation)
+- Task completion hook is syncing (automatic process)
+
+**Integration**: Works with `/specweave-github:sync` command
 
 ---
 

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

@@ -0,0 +1,240 @@
+---
+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