zhongwei/gh-anton-abyzov-specweave-plugins-specweave-jira
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
93c16ce8f26ca666ef00e6d294b14363f7248f4a
gh-anton-abyzov-specweave-p…/commands/specweave-jira-sync.md
Zhongwei Li 93c16ce8f2 Initial commit
2025-11-29 17:56:44 +08:00

7.1 KiB
Raw Blame History

name, description
name description
specweave-jira:sync Sync SpecWeave increments with JIRA epics/stories. Supports import, export, two-way sync, and granular item operations

Sync Jira Command

You are a Jira synchronization expert. Help the user sync between Jira and SpecWeave with granular control.

Available Operations

Epic-Level Operations

1. Two-way Sync (Default - Recommended)

/specweave-jira:sync 0003                    # Two-way sync (default)
/specweave-jira:sync 0003 --direction two-way  # Explicit

2. Import Jira Epic as SpecWeave Increment

/specweave-jira:sync import SCRUM-123        # One-time pull
/specweave-jira:sync SCRUM-123 --direction from-jira  # Same as import

3. Export SpecWeave Increment to Jira

/specweave-jira:sync export 0001             # One-time push
/specweave-jira:sync 0001 --direction to-jira  # Same as export

Sync Direction Options

Default: two-way (both directions - recommended)

  • --direction two-way: SpecWeave ↔ Jira (default)

    • Pull changes FROM Jira (status, priority, comments)
    • Push changes TO Jira (tasks, progress, metadata)

  • --direction to-jira: SpecWeave → Jira only

    • Push increment progress to Jira
    • Don't pull Jira changes back
    • Same as export operation

  • --direction from-jira: Jira → SpecWeave only

    • Pull Jira issue updates
    • Don't push SpecWeave changes
    • Same as import operation

Granular Item Operations

4. Add specific Story/Bug/Task to existing Increment

/specweave-jira:sync add SCRUM-1 to 0003
/specweave-jira:sync add SCRUM-1              # Adds to current increment

5. Create Increment from specific items (cherry-pick)

/specweave-jira:sync create "User Authentication" from SCRUM-1 SCRUM-5 SCRUM-7
/specweave-jira:sync create "Bug Fixes Sprint 1" from SCRUM-10 SCRUM-15 SCRUM-20

6. Show sync status

/specweave-jira:sync status
/specweave-jira:sync status 0003              # Status of specific increment

Your Task

When the user runs this command:

  1. Parse the command arguments:

    • Operation: import, sync, export, add, create, or status
    • ID: Jira Epic key (e.g., SCRUM-123) or Increment ID (e.g., 0001)

  2. Execute the operation:

    For import Epic:

    import { JiraClient } from './src/integrations/jira/jira-client';
import { JiraMapper } from './src/integrations/jira/jira-mapper';

const client = new JiraClient();
const mapper = new JiraMapper(client);
const result = await mapper.importEpicAsIncrement('SCRUM-123');

    For add item:

    import { JiraIncrementalMapper } from './src/integrations/jira/jira-incremental-mapper';

const incrementalMapper = new JiraIncrementalMapper(client);
const result = await incrementalMapper.addItemToIncrement('0003', 'SCRUM-1');

    For create from items:

    const result = await incrementalMapper.createIncrementFromItems(
  'User Authentication',
  ['SCRUM-1', 'SCRUM-5', 'SCRUM-7']
);

    For sync:

    const result = await mapper.syncIncrement('0003');

    For export:

    const result = await mapper.exportIncrementAsEpic('0001', 'SCRUM');

  3. Show results:

    • Display sync summary
    • Show conflicts (if any)
    • List created/updated files
    • Provide links to Jira and SpecWeave

  4. Handle errors gracefully:

    • Check if .env credentials exist
    • Validate increment/epic exists
    • Show clear error messages

Examples

Example 1: Import Epic

User: /specweave:sync-jira import SCRUM-2 You:

  • Import Epic SCRUM-2 from Jira
  • Show: "✅ Imported as Increment 0004"
  • List: "Created: spec.md, tasks.md, RFC document"
  • Link: "Jira: https://... | Increment: .specweave/increments/0004/"

Example 2: Add Story to Current Increment

User: /specweave:sync-jira add SCRUM-1 You:

  • Determine current increment (latest or from context)
  • Fetch SCRUM-1 from Jira
  • Add to increment's spec.md (under ## User Stories)
  • Update tasks.md
  • Update RFC
  • Show: "✅ Added Story SCRUM-1 to Increment 0003"
  • Display: "Type: story | Title: User can login | Status: in-progress"

Example 3: Add Bug to Specific Increment

User: /specweave:sync-jira add SCRUM-10 to 0003 You:

  • Fetch SCRUM-10 from Jira (it's a Bug)
  • Add to increment 0003's spec.md (under ## Bugs)
  • Update tasks.md
  • Update RFC
  • Show: "✅ Added Bug SCRUM-10 to Increment 0003"
  • Display: "Type: bug | Priority: P1 | Title: Fix login redirect"

Example 4: Create Increment from Multiple Items

User: /specweave:sync-jira create "User Authentication" from SCRUM-1 SCRUM-5 SCRUM-7 You:

  • Fetch all 3 issues from Jira
  • Determine types (story, bug, task)
  • Create new increment 0005
  • Group by type in spec.md:

    • User Stories (SCRUM-1, SCRUM-5)

    • Technical Tasks (SCRUM-7)

  • Generate RFC with all items
  • Show: "✅ Created Increment 0005 with 3 work items"
  • Display table: 
    | Type  | Jira Key | Title           |
|-------|----------|-----------------|
| Story | SCRUM-1  | User login UI   |
| Story | SCRUM-5  | OAuth backend   |
| Task  | SCRUM-7  | Setup provider  |

Example 5: Two-way Sync (Default)

User: /specweave-jira:sync 0003 You:

  • Read increment 0003
  • Find linked Jira items (from spec.md frontmatter.work_items)
  • Fetch current state from Jira

Detect changes (both directions):

  • FROM Jira: Status changes, priority updates, comments
  • FROM SpecWeave: Task completion, progress updates

Show two-way sync summary:

✅ Two-way Sync Complete: 0003 ↔ Jira

FROM Jira:
  • SCRUM-1: Status changed to In Progress
  • SCRUM-10: Priority raised to P1

FROM SpecWeave:
  • 3 tasks completed (T-005, T-006, T-007)
  • Progress: 60% → 75%

Conflicts: None

Handle conflicts if any:

  • Show both versions (Jira vs SpecWeave)
  • Ask user which to keep or how to merge
  • Apply resolution in both directions

Example 6: Status Overview

User: /specweave-jira:sync status You:

  • Scan all increments for Jira metadata
  • Show table: 
    | Increment | Title            | Jira Items | Last Sync          |
|-----------|------------------|------------|--------------------|
| 0003      | Test Epic        | 0 items    | 2025-10-28 17:42   |
| 0004      | User Auth        | 3 items    | 2025-10-28 18:00   |
| 0005      | Bug Fixes        | 5 items    | Never              |

Important Notes

  • Always check if .env has Jira credentials before syncing
  • Never log secrets or tokens
  • Show clear progress messages
  • Display rich output with links
  • Save sync results to test-results/ if requested

Related Commands

  • /specweave-github:sync - Sync to GitHub issues (also two-way by default)
  • /specweave:increment - Create new increment
  • /specweave:validate - Validate increment quality

Two-way by Default: All sync operations are two-way unless you explicitly specify --direction to-jira or --direction from-jira. This keeps both systems synchronized automatically.

Granular Control: Unlike simple epic import/export, this command supports cherry-picking individual stories, bugs, and tasks for maximum flexibility.

Reference in New Issue View Git Blame Copy Permalink