specweave 0.12.0 → 0.12.2

package/plugins/specweave-jira/lib/jira-spec-sync.ts

@@ -0,0 +1,582 @@
+/**
+ * Jira Spec Sync
+ *
+ * CORRECT ARCHITECTURE:
+ * - Syncs .specweave/docs/internal/specs/spec-*.md ↔ Jira Epics
+ * - NOT increments ↔ Jira Issues (that was wrong!)
+ *
+ * Mapping:
+ * - Spec → Jira Epic
+ * - User Story → Jira Story (subtask of epic)
+ * - Acceptance Criteria → Checklist in Story description
+ *
+ * @module jira-spec-sync
+ */
+
+import { SpecMetadataManager } from '../../../src/core/specs/spec-metadata-manager.js';
+import { SpecParser } from '../../../src/core/specs/spec-parser.js';
+import {
+  SpecContent,
+  UserStory,
+  SpecSyncResult,
+  SpecSyncConflict
+} from '../../../src/core/types/spec-metadata.js';
+import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+import axios, { AxiosInstance } from 'axios';
+
+export interface JiraEpic {
+  id: string;
+  key: string; // e.g., SPEC-1
+  summary: string;
+  description: string;
+  status: {
+    name: string; // To Do, In Progress, Done
+  };
+  url: string;
+}
+
+export interface JiraStory {
+  id: string;
+  key: string; // e.g., SPEC-2
+  summary: string;
+  description: string;
+  status: {
+    name: string;
+  };
+  epicLink?: string; // Epic key
+  labels: string[];
+}
+
+export interface JiraConfig {
+  domain: string; // e.g., company.atlassian.net
+  email: string;
+  apiToken: string;
+  projectKey: string; // e.g., SPEC
+}
+
+export class JiraSpecSync {
+  private specManager: SpecMetadataManager;
+  private client: AxiosInstance;
+  private config: JiraConfig;
+
+  constructor(config: JiraConfig, projectRoot: string = process.cwd()) {
+    this.specManager = new SpecMetadataManager(projectRoot);
+    this.config = config;
+
+    // Create Jira API client
+    this.client = axios.create({
+      baseURL: `https://${config.domain}/rest/api/3`,
+      auth: {
+        username: config.email,
+        password: config.apiToken
+      },
+      headers: {
+        'Accept': 'application/json',
+        'Content-Type': 'application/json'
+      }
+    });
+  }
+
+  /**
+   * Sync spec to Jira Epic (CREATE or UPDATE)
+   */
+  async syncSpecToJira(specId: string): Promise<SpecSyncResult> {
+    console.log(`\n🔄 Syncing spec ${specId} to Jira Epic...`);
+
+    try {
+      // 1. Load spec
+      const spec = await this.specManager.loadSpec(specId);
+      if (!spec) {
+        return {
+          success: false,
+          specId,
+          provider: 'jira',
+          error: `Spec ${specId} not found`
+        };
+      }
+
+      // 2. Check if spec already linked to Jira Epic
+      const existingLink = spec.metadata.externalLinks?.jira;
+
+      let epic: JiraEpic;
+
+      if (existingLink?.epicKey) {
+        // UPDATE existing epic
+        console.log(`   Found existing Jira Epic ${existingLink.epicKey}`);
+        epic = await this.updateJiraEpic(existingLink.epicKey, spec);
+      } else {
+        // CREATE new epic
+        console.log('   Creating new Jira Epic...');
+        epic = await this.createJiraEpic(spec);
+
+        // Link spec to epic
+        await this.specManager.linkToExternal(specId, 'jira', {
+          id: epic.key,
+          url: epic.url,
+          projectKey: this.config.projectKey,
+          domain: this.config.domain
+        });
+      }
+
+      // 3. Sync user stories as Jira Stories
+      const changes = await this.syncUserStories(epic.key, spec);
+
+      console.log('✅ Sync complete!');
+
+      return {
+        success: true,
+        specId,
+        provider: 'jira',
+        externalId: epic.key,
+        url: epic.url,
+        changes
+      };
+
+    } catch (error) {
+      console.error('❌ Error syncing to Jira:', error);
+      return {
+        success: false,
+        specId,
+        provider: 'jira',
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  /**
+   * Sync FROM Jira Epic to spec (bidirectional)
+   */
+  async syncFromJira(specId: string): Promise<SpecSyncResult> {
+    console.log(`\n🔄 Syncing FROM Jira to spec ${specId}...`);
+
+    try {
+      // 1. Load spec
+      const spec = await this.specManager.loadSpec(specId);
+      if (!spec) {
+        return {
+          success: false,
+          specId,
+          provider: 'jira',
+          error: `Spec ${specId} not found`
+        };
+      }
+
+      // 2. Get Jira Epic link
+      const jiraLink = spec.metadata.externalLinks?.jira;
+      if (!jiraLink?.epicKey) {
+        return {
+          success: false,
+          specId,
+          provider: 'jira',
+          error: 'Spec not linked to Jira Epic'
+        };
+      }
+
+      // 3. Fetch Jira Epic state
+      const epic = await this.fetchJiraEpic(jiraLink.epicKey);
+
+      // 4. Detect conflicts
+      const conflicts = await this.detectConflicts(spec, epic);
+
+      if (conflicts.length === 0) {
+        console.log('✅ No conflicts - spec and Jira in sync');
+        return {
+          success: true,
+          specId,
+          provider: 'jira',
+          externalId: epic.key,
+          url: epic.url
+        };
+      }
+
+      console.log(`⚠️  Detected ${conflicts.length} conflict(s)`);
+
+      // 5. Resolve conflicts (Jira wins by default for now)
+      await this.resolveConflicts(spec, conflicts);
+
+      console.log('✅ Sync FROM Jira complete!');
+
+      return {
+        success: true,
+        specId,
+        provider: 'jira',
+        externalId: epic.key,
+        url: epic.url,
+        conflicts
+      };
+
+    } catch (error) {
+      console.error('❌ Error syncing FROM Jira:', error);
+      return {
+        success: false,
+        specId,
+        provider: 'jira',
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  /**
+   * Create new Jira Epic for spec
+   */
+  private async createJiraEpic(spec: SpecContent): Promise<JiraEpic> {
+    const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    const epicDescription = this.generateEpicDescription(spec);
+
+    const payload = {
+      fields: {
+        project: {
+          key: this.config.projectKey
+        },
+        summary: epicSummary,
+        description: epicDescription,
+        issuetype: {
+          name: 'Epic'
+        },
+        labels: [`spec:${spec.metadata.id}`, `priority:${spec.metadata.priority}`]
+      }
+    };
+
+    const response = await this.client.post('/issue', payload);
+    const epicData = response.data;
+
+    const epicKey = epicData.key;
+    const epicUrl = `https://${this.config.domain}/browse/${epicKey}`;
+
+    console.log(`   ✅ Created Jira Epic ${epicKey}: ${epicUrl}`);
+
+    return {
+      id: epicData.id,
+      key: epicKey,
+      summary: epicSummary,
+      description: epicDescription,
+      status: { name: 'To Do' },
+      url: epicUrl
+    };
+  }
+
+  /**
+   * Update existing Jira Epic
+   */
+  private async updateJiraEpic(epicKey: string, spec: SpecContent): Promise<JiraEpic> {
+    const epicSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    const epicDescription = this.generateEpicDescription(spec);
+
+    const payload = {
+      fields: {
+        summary: epicSummary,
+        description: epicDescription
+      }
+    };
+
+    await this.client.put(`/issue/${epicKey}`, payload);
+
+    // Fetch updated epic
+    const response = await this.client.get(`/issue/${epicKey}`);
+    const epicData = response.data;
+
+    console.log(`   ✅ Updated Jira Epic ${epicKey}`);
+
+    return {
+      id: epicData.id,
+      key: epicKey,
+      summary: epicData.fields.summary,
+      description: epicData.fields.description,
+      status: epicData.fields.status,
+      url: `https://${this.config.domain}/browse/${epicKey}`
+    };
+  }
+
+  /**
+   * Sync user stories as Jira Stories
+   */
+  private async syncUserStories(
+    epicKey: string,
+    spec: SpecContent
+  ): Promise<{ created: string[]; updated: string[]; deleted: string[] }> {
+    const created: string[] = [];
+    const updated: string[] = [];
+    const deleted: string[] = [];
+
+    if (!spec.metadata.userStories || spec.metadata.userStories.length === 0) {
+      console.log('   ℹ️  No user stories to sync');
+      return { created, updated, deleted };
+    }
+
+    console.log(`   Syncing ${spec.metadata.userStories.length} user stories...`);
+
+    for (const us of spec.metadata.userStories) {
+      // Create or update Jira Story for each user story
+      const storySummary = `[${us.id}] ${us.title}`;
+      const storyDescription = this.generateStoryDescription(us);
+
+      // Check if story already exists (by searching for US-ID in summary)
+      const existingStory = await this.findStoryByTitle(us.id);
+
+      if (existingStory) {
+        // UPDATE existing story
+        await this.updateStory(existingStory.key, {
+          summary: storySummary,
+          description: storyDescription,
+          status: us.status === 'done' ? 'Done' : us.status === 'in-progress' ? 'In Progress' : 'To Do'
+        });
+
+        updated.push(us.id);
+        console.log(`   ✅ Updated ${us.id}`);
+      } else {
+        // CREATE new story
+        const newStory = await this.createStory({
+          summary: storySummary,
+          description: storyDescription,
+          epicLink: epicKey,
+          labels: [`user-story`, `spec:${spec.metadata.id}`, `priority:${us.priority}`]
+        });
+
+        created.push(us.id);
+        console.log(`   ✅ Created ${us.id} → Story ${newStory.key}`);
+      }
+    }
+
+    return { created, updated, deleted };
+  }
+
+  /**
+   * Generate epic description from spec
+   */
+  private generateEpicDescription(spec: SpecContent): string {
+    const progress = spec.metadata.progress;
+    const progressText = progress
+      ? `*Progress*: ${progress.percentComplete}% (${progress.completedUserStories}/${progress.totalUserStories} user stories)`
+      : '*Progress*: N/A';
+
+    return `
+h1. ${spec.metadata.title}
+
+*Spec ID*: ${spec.metadata.id}
+*Priority*: ${spec.metadata.priority}
+*Status*: ${spec.metadata.status}
+${progressText}
+
+----
+
+${SpecParser.extractOverview(spec.markdown)}
+
+----
+
+h2. User Stories
+
+${spec.metadata.userStories?.length || 0} user stories tracked in this epic.
+
+----
+
+🤖 *Auto-synced from SpecWeave*
+Last updated: ${new Date().toISOString()}
+`.trim();
+  }
+
+  /**
+   * Generate story description from user story
+   */
+  private generateStoryDescription(us: UserStory): string {
+    const acList = us.acceptanceCriteria
+      .map(ac => `* ${ac.status === 'done' ? '(/)' : '(x)'} ${ac.description}`)
+      .join('\n');
+
+    return `
+h2. User Story
+
+${us.title}
+
+h2. Acceptance Criteria
+
+${acList}
+
+----
+
+*Priority*: ${us.priority}
+*Status*: ${us.status}
+
+🤖 *Auto-synced from SpecWeave*
+`.trim();
+  }
+
+  /**
+   * Detect conflicts between spec and Jira
+   */
+  private async detectConflicts(
+    spec: SpecContent,
+    epic: JiraEpic
+  ): Promise<SpecSyncConflict[]> {
+    const conflicts: SpecSyncConflict[] = [];
+
+    // Compare epic summary
+    const expectedSummary = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    if (epic.summary !== expectedSummary) {
+      conflicts.push({
+        type: 'metadata',
+        field: 'title',
+        localValue: spec.metadata.title,
+        remoteValue: epic.summary,
+        resolution: 'remote-wins',
+        description: 'Epic summary differs from spec title'
+      });
+    }
+
+    // TODO: Compare user stories and their statuses
+
+    return conflicts;
+  }
+
+  /**
+   * Resolve conflicts
+   */
+  private async resolveConflicts(
+    spec: SpecContent,
+    conflicts: SpecSyncConflict[]
+  ): Promise<void> {
+    for (const conflict of conflicts) {
+      if (conflict.resolution === 'remote-wins') {
+        console.log(`   🔄 Resolving: ${conflict.description} (Jira wins)`);
+        // Update spec metadata from Jira
+        if (conflict.field === 'title') {
+          await this.specManager.saveMetadata(spec.metadata.id, {
+            title: conflict.remoteValue
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Fetch Jira Epic details
+   */
+  private async fetchJiraEpic(epicKey: string): Promise<JiraEpic> {
+    const response = await this.client.get(`/issue/${epicKey}`);
+    const epicData = response.data;
+
+    return {
+      id: epicData.id,
+      key: epicKey,
+      summary: epicData.fields.summary,
+      description: epicData.fields.description,
+      status: epicData.fields.status,
+      url: `https://${this.config.domain}/browse/${epicKey}`
+    };
+  }
+
+  /**
+   * Find story by title pattern
+   */
+  private async findStoryByTitle(usId: string): Promise<JiraStory | null> {
+    const jql = `project = ${this.config.projectKey} AND summary ~ "[${usId}]" AND issuetype = Story`;
+
+    const response = await this.client.get('/search', {
+      params: {
+        jql,
+        maxResults: 1,
+        fields: 'summary,description,status,labels'
+      }
+    });
+
+    const issues = response.data.issues;
+    return issues.length > 0 ? {
+      id: issues[0].id,
+      key: issues[0].key,
+      summary: issues[0].fields.summary,
+      description: issues[0].fields.description,
+      status: issues[0].fields.status,
+      labels: issues[0].fields.labels || []
+    } : null;
+  }
+
+  /**
+   * Create Jira Story
+   */
+  private async createStory(story: {
+    summary: string;
+    description: string;
+    epicLink: string;
+    labels: string[];
+  }): Promise<JiraStory> {
+    const payload = {
+      fields: {
+        project: {
+          key: this.config.projectKey
+        },
+        summary: story.summary,
+        description: story.description,
+        issuetype: {
+          name: 'Story'
+        },
+        labels: story.labels,
+        // Link to epic (field name may vary by Jira configuration)
+        customfield_10014: story.epicLink // Epic Link field (adjust if needed)
+      }
+    };
+
+    const response = await this.client.post('/issue', payload);
+    const storyData = response.data;
+
+    return {
+      id: storyData.id,
+      key: storyData.key,
+      summary: story.summary,
+      description: story.description,
+      status: { name: 'To Do' },
+      labels: story.labels
+    };
+  }
+
+  /**
+   * Update Jira Story
+   */
+  private async updateStory(
+    storyKey: string,
+    updates: { summary?: string; description?: string; status?: string }
+  ): Promise<void> {
+    const payload: any = {
+      fields: {}
+    };
+
+    if (updates.summary) {
+      payload.fields.summary = updates.summary;
+    }
+
+    if (updates.description) {
+      payload.fields.description = updates.description;
+    }
+
+    await this.client.put(`/issue/${storyKey}`, payload);
+
+    // Handle status transition if needed
+    if (updates.status) {
+      await this.transitionIssue(storyKey, updates.status);
+    }
+  }
+
+  /**
+   * Transition issue to new status
+   */
+  private async transitionIssue(issueKey: string, targetStatus: string): Promise<void> {
+    // Get available transitions
+    const transitionsResponse = await this.client.get(`/issue/${issueKey}/transitions`);
+    const transitions = transitionsResponse.data.transitions;
+
+    // Find transition matching target status
+    const transition = transitions.find(
+      (t: any) => t.to.name.toLowerCase() === targetStatus.toLowerCase()
+    );
+
+    if (!transition) {
+      console.warn(`   ⚠️  Cannot transition ${issueKey} to ${targetStatus} (no valid transition)`);
+      return;
+    }
+
+    // Execute transition
+    await this.client.post(`/issue/${issueKey}/transitions`, {
+      transition: {
+        id: transition.id
+      }
+    });
+  }
+}

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

@@ -1,6 +1,6 @@
 ---
 name: jira-sync
-description: Bidirectional sync between SpecWeave increments and JIRA epics/stories (two-way sync by default). Activates for JIRA sync, create JIRA issue, import from JIRA, sync to JIRA, bidirectional JIRA sync. Coordinates with specweave-jira-mapper agent.
+description: Bidirectional sync between SpecWeave increments and JIRA epics/stories (two-way sync by default). Activates ONLY when user asks questions about JIRA integration or needs help configuring JIRA sync. Does NOT activate for slash commands. For syncing, use /specweave-jira:sync command instead. Coordinates with specweave-jira-mapper agent.
 allowed-tools: Read, Write, Edit, Task, Bash
 ---
 
@@ -10,12 +10,27 @@ Coordinates JIRA synchronization by delegating to `specweave-jira-mapper` agent.
 
 **Default Behavior**: **Bidirectional (two-way) sync** - Changes synchronized in both directions automatically
 
+**⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about JIRA sync. For actual syncing, users should use the `/specweave-jira:sync` command directly. This skill should NOT auto-activate when the command is being invoked.
+
+## When to Activate
+
+✅ **Do activate when**:
+- User asks: "How do I set up JIRA sync?"
+- User asks: "What JIRA credentials do I need?"
+- User asks: "How does bidirectional sync work?"
+- User needs help configuring JIRA integration
+
+❌ **Do NOT activate when**:
+- User invokes `/specweave-jira:sync` command (command handles it)
+- Command is already running (avoid duplicate invocation)
+- Task completion hook is syncing (automatic process)
+
 ## Responsibilities
 
-1. Detect sync requests (bidirectional by default, or export/import if specified)
-2. Validate prerequisites (JIRA credentials, increment structure)
-3. Invoke `specweave-jira-mapper` agent with sync direction
-4. Handle errors gracefully
+1. Answer questions about JIRA sync configuration
+2. Help validate prerequisites (JIRA credentials, increment structure)
+3. Explain sync direction options (bidirectional, export, import)
+4. Provide troubleshooting guidance
 
 ---
 

package/src/templates/AGENTS.md.template

@@ -428,9 +428,19 @@ When you complete a task (mark todo as done), the hook:
 
 #### For Other AI Tools (Manual ⚠️)
 
-**⚠️ IMPORTANT**: After completing EACH task, manually update tasks.md:
+**⚠️ IMPORTANT**: After completing EACH task, run these slash commands to keep everything in sync:
 
-**Step-by-Step**:
+**Quick Commands** (copy-paste friendly):
+
+```bash
+# After completing a task, run these three commands:
+
+/specweave:sync-tasks                  # 1. Update tasks.md completion status
+/specweave:sync-docs update            # 2. Sync to living docs
+/specweave-github:sync <increment-id>  # 3. Sync to GitHub (replace <increment-id> with your increment, e.g., 0007)
+```
+
+**Alternative: Manual Update** (if slash commands unavailable):
 
 ```bash
 # Example: You just completed T-001
@@ -1356,15 +1366,51 @@ Only **Claude Code** has automatic hooks (via `post-task-completion.sh`) that sy
 
 ### Summary Checklist (After Every Task)
 
-When you complete a task in non-Claude tools:
+When you complete a task in non-Claude tools, **run these slash commands**:
+
+#### Quick Sync (After Each Task Completion)
+
+```bash
+# 1. Sync tasks.md with completion status
+/specweave:sync-tasks
+
+# 2. Update living docs from completed work
+/specweave:sync-docs update
+```
+
+#### External Tracker Sync (If Enabled)
+
+```bash
+# 3. Sync to external tracker (choose one based on your setup):
+
+# GitHub Issues:
+/specweave-github:sync <increment-id>
+
+# Jira:
+/specweave-jira:sync <increment-id>
+
+# Azure DevOps:
+/specweave-ado:sync <increment-id>
+```
+
+#### Example Full Workflow
 
-1. ✅ Mark task complete in tasks.md
-2. ✅ Update living docs (see "Documentation Updates" section)
-3. ✅ **Sync to GitHub/Jira/ADO** (this section)
-4. ✅ Update RFC if applicable (if task implements architecture decision)
-5. ✅ Continue to next task
+```bash
+# After completing a task in your current increment:
+
+# Step 1: Update tasks.md
+/specweave:sync-tasks
+
+# Step 2: Sync living docs
+/specweave:sync-docs update
+
+# Step 3: Sync to GitHub (if using GitHub tracking)
+/specweave-github:sync <increment-id>  # e.g., /specweave-github:sync 0016
+
+# Done! Continue to next task.
+```
 
-**Remember**: In Claude Code, steps 3-4 happen automatically via hooks. In other tools, YOU must do them manually!
+**Remember**: In Claude Code, all of this happens **automatically via hooks**. In other tools (Cursor, Copilot, ChatGPT), **YOU must run these commands manually** after each task!
 
 ---
 

package/dist/cli/commands/docs-build.d.ts

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-/**
- * CLI command for /specweave:docs build
- * Build static documentation site for deployment
- */
-export {};
-//# sourceMappingURL=docs-build.d.ts.map

package/dist/cli/commands/docs-build.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"docs-build.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/docs-build.ts"],"names":[],"mappings":";AAEA;;;GAGG"}