Jira Synchronization System Guide

Overview

The TC Portal Jira sync system keeps local initiative folders perfectly synchronized with Jira as the single source of truth. This guide explains the architecture, workflows, and how to use the unified sync system.

Architecture

┌─────────────────────────────────────────────────┐
│         USER COMMANDS (Entry Points)             │
│  /jira-setup  /jira-sync  /jira-stories         │
└───────────────────┬─────────────────────────────┘
                    │ invoke
┌───────────────────▼─────────────────────────────┐
│      PRODUCT MANAGER AGENT (Orchestrator)       │
│   Manages all Jira sync operations              │
└───────────────────┬─────────────────────────────┘
                    │ uses
┌───────────────────▼─────────────────────────────┐
│         JIRA SKILLS (/.claude/skills/)     │
│  ┌──────────────┐  ┌──────────────┐            │
│  │ folder-sync  │  │ stories-sync │            │
│  └──────────────┘  └──────────────┘            │
│  ┌──────────────┐  ┌──────────────┐            │
│  │ phase-mgmt   │  │ archive      │            │
│  └──────────────┘  └──────────────┘            │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│      DATA LAYER (Source of Truth: Jira)         │
│  - Initiatives (TP-XXXX)                        │
│  - Epics (TP-YYYY)                               │
│  - Stories/Tasks                                 │
│  - Phase structure                               │
└─────────────────────────────────────────────────┘

Components

1. Commands (User Interface)

Location: .claude/commands/jira-*.md

Command	Purpose	Example
`/jira-setup`	Initial OAuth authentication	`/jira-setup`
`/jira-sync`	Main sync command with flags	`/jira-sync --epic TP-1904`
`/jira-stories`	Import user stories CSV to Jira	`/jira-stories`

2. Product Manager Agent (Orchestrator)

Location: .claude/agents/product-manager-agent (WILL).md

Role: Orchestrates all Jira sync operations by invoking specialized skills.

Capabilities:

Full system sync (all initiatives/epics)
Targeted sync (single epic/initiative)
Archive management
Phase validation
Progress tracking

3. Jira Skills (Specialized Workers)

Location: .claude/skills/

a) folder-sync.md

Purpose: Bidirectional folder structure synchronization

Operations:

Create folders for new initiatives/epics
Rename folders when summaries change
Move folders when parent changes
Archive folders for closed epics

Key File: INITIATIVES/sync-manifest.json

b) stories-sync.md

Purpose: Sync stories.json files with Jira

Operations:

Fetch stories from Jira for epic
Compare with local stories.json
Update with Jira changes
Handle conflicts (warn, don’t overwrite)

Key File: [epic-folder]/stories.json

c) phase-management.md

Purpose: Manage phase structure for epics

Operations:

Discover existing phase patterns
Create missing phases (Discovery, Design, Development, QA, Release)
Generate coverage reports
Validate phase naming/types

Jira Issue Type: Phases (ID: 10399)

d) archive-handler.md

Purpose: Archive closed epics with metadata

Operations:

Move epic to ARCHIVED/[date]_[name]/
Create archive-metadata.json
Preserve all files
Update sync-manifest.json

Key Directory: INITIATIVES/ARCHIVED/

Common Workflows

Workflow 1: Daily Sync

Goal: Keep everything in sync with Jira

# Full sync (recommended daily)
/jira-sync

# Or with dry-run first to preview
/jira-sync --dry-run
/jira-sync

What happens:

Syncs folder structure (new/renamed/moved epics)
Archives closed epics
Updates all stories.json files
Updates sync-manifest.json
Generates sync report

Workflow 2: Working on Specific Epic

Goal: Sync just one epic before starting work

# Sync single epic
/jira-sync --epic TP-1904

# Review changes
cat INITIATIVES/.../TP-1904-*/stories.json

What happens:

Fetches latest stories for TP-1904
Updates stories.json
Shows what changed

Workflow 3: Initiative Planning

Goal: Sync all epics under an initiative

# Sync entire initiative
/jira-sync --initiative TP-1859

# Validate phases
/jira-sync --initiative TP-1859 --phases

What happens:

Syncs all epics under TP-1859
Validates/creates missing phases
Reports coverage status

Workflow 4: Cleanup Closed Work

Goal: Archive all completed epics

# Archive closed epics only
/jira-sync --archive-closed

What happens:

Finds all closed epics
Moves to ARCHIVED/[date]_[name]/
Creates archive-metadata.json
Updates sync-manifest.json

Workflow 5: Phase Management

Goal: Ensure all epics have proper phases

# Validate phases for initiative
/jira-sync --initiative TP-1869 --phases

# Or for all epics
/jira-sync --phases

What happens:

Checks each epic for 5 required phases
Creates missing phases
Validates naming format
Generates coverage report

Folder Structure

INITIATIVES/
├── sync-manifest.json                    # Sync state (DO NOT EDIT MANUALLY)
│
├── TP-1859-Clinical-And-Care-Plan/      # Initiative folder
│   │
│   ├── TP-1904-ASS-Assessments/         # Epic folder
│   │   ├── stories.json                 # Synced from Jira
│   │   ├── PRD.md                       # Product Requirements
│   │   ├── RACI.md                      # RACI matrix
│   │   ├── idea.md                     # Original idea brief
│   │   ├── JIRA-DUMP/                   # Jira data backup
│   │   │   ├── epic.json
│   │   │   └── issues.json
│   │   └── USER-STORIES/                # Legacy (optional)
│   │       └── user-stories.csv
│   │
│   └── TP-1905-NEXT-Next-Epic/
│       └── ...
│
├── TP-1869-Budgets-And-Services/
│   └── ...
│
└── ARCHIVED/                             # Closed epics (reference)
    └── 2025-11_TP-1900-OLD-Old-Epic/    # Archived with date prefix
        ├── archive-metadata.json        # Closure details
        ├── stories.json                 # Final state
        ├── PRD.md
        ├── RACI.md
        └── JIRA-DUMP/

sync-manifest.json Structure

DO NOT EDIT MANUALLY - Updated by sync operations

{
  "lastSync": "2025-11-07T10:30:00Z",
  "initiatives": [
    {
      "key": "TP-1859",
      "name": "Clinical & Care Plan",
      "folderName": "TP-1859-Clinical-And-Care-Plan",
      "epicsCount": 6,
      "epics": [
        {
          "key": "TP-1904",
          "name": "Assessments / Prescriptions",
          "prefix": "ASS",
          "folderName": "TP-1904-ASS-Assessments",
          "status": "In Progress",
          "storiesCount": 12,
          "lastVerified": "2025-11-07T10:30:00Z"
        }
      ]
    }
  ]
}

stories.json Structure

{
  "epic": {
    "key": "TP-1904",
    "summary": "Assessments / Prescriptions",
    "status": "In Progress",
    "dueDate": "2026-01-09"
  },
  "stories": [
    {
      "key": "TP-1234",
      "summary": "User can create assessment",
      "description": "As a care coordinator...",
      "status": "In Progress",
      "storyPoints": 5,
      "assignee": "jane@example.com",
      "priority": "P0",
      "acceptanceCriteria": [
        "Display assessment form",
        "Validate inputs",
        "Save to database"
      ],
      "tasks": [
        {
          "key": "TP-1235",
          "summary": "Design schema",
          "status": "Done"
        }
      ]
    }
  ],
  "syncMetadata": {
    "lastSyncedAt": "2025-11-07T10:30:00Z",
    "lastSyncedBy": "product-manager-agent",
    "totalStories": 12,
    "completedStories": 8
  }
}

Naming Conventions

Initiatives

TP-XXXX-Initiative-Name

Example: TP-1869-Budgets-And-Services

Epics

TP-XXXX-[PREFIX]-Epic-Name

TP-XXXX = Jira epic key
[PREFIX] = 3-letter epic code (optional)
Epic-Name = kebab-case summary

Examples:

TP-1906-QRW-QR-Code-Service-Confirmation
TP-970-Confirmation-Of-Service-Delivery (no prefix)

Archived Epics

YYYY-MM_TP-XXXX-[PREFIX]-Epic-Name

Example: 2025-11_TP-1900-OLD-Old-Feature

Phases

[CODE] - [PHASE_NAME]

Example: ASS - Development

Required phases:

Discovery
Design
Development
QA
Release

Best Practices

Daily Operations

✅ Run /jira-sync at start of day
✅ Run /jira-sync --epic TP-XXXX before working on epic
✅ Run /jira-sync --dry-run before major sync operations
✅ Review sync reports for unexpected changes

Safety

✅ Always use --dry-run for destructive operations
✅ sync-manifest.json is backed up automatically
✅ Archived folders are never deleted
✅ Git tracks all changes for rollback

Performance

✅ Use targeted sync (--epic, --initiative) when possible
✅ Use --structure-only for quick folder updates
✅ Use --stories-only to skip folder operations
✅ Full sync is optimized but takes 10-30 seconds

Conflict Resolution

✅ Jira is ALWAYS the source of truth
✅ Local changes in stories.json will be warned (not overwritten)
✅ Manual folder changes are detected and warned
✅ If conflict persists, delete local and resync

Troubleshooting

Problem: Sync fails with “Epic not found”

Solution:

# Verify epic exists in Jira
/jira-sync --epic TP-XXXX --dry-run

# Check sync-manifest.json for stale entries
cat INITIATIVES/sync-manifest.json | grep TP-XXXX

Problem: Folder structure out of sync

Solution:

# Force structure sync
/jira-sync --structure-only

# Review changes
git status INITIATIVES/

Problem: stories.json has conflicts

Solution:

Backup local changes: cp stories.json stories.json.backup
Resync from Jira: /jira-sync --epic TP-XXXX
Manually merge if needed

Problem: Archive operation failed

Solution:

# Check epic status in Jira
# (Must be "Closed" or "Done")

# Retry archive
/jira-sync --archive-closed

# Manual archive if needed
# (See .claude/skills/archive-handler.md)

Advanced Usage

Custom Sync Workflows

# Sync structure, then validate phases
/jira-sync --structure-only
/jira-sync --phases

# Archive closed, then sync open epics
/jira-sync --archive-closed
/jira-sync --stories-only

# Full sync with dump
/jira-sync
/jira-sync --dump

Integration with Other Commands

# Planning workflow
/prd TP-1904           # Generate PRD
/stories               # Generate user stories CSV
/jira-stories          # Import to Jira
/jira-sync --epic TP-1904  # Sync back to local

# Release workflow
/track TP-1904         # Update epic progress
/jira-sync --epic TP-1904  # Sync latest status
/changelog             # Generate changelog

Product Manager Agent: .claude/agents/product-manager-agent (WILL).md
Jira Skills: .claude/skills/
Commands: .claude/commands/jira-*.md
Atlassian MCP: Available MCP tools for Jira/Confluence

Quick Reference Card

Task	Command
Daily sync	`/jira-sync`
Sync one epic	`/jira-sync --epic TP-XXXX`
Sync initiative	`/jira-sync --initiative TP-XXXX`
Preview changes	`/jira-sync --dry-run`
Archive closed	`/jira-sync --archive-closed`
Validate phases	`/jira-sync --phases`
Structure only	`/jira-sync --structure-only`
Stories only	`/jira-sync --stories-only`
Initial setup	`/jira-setup`
Import stories	`/jira-stories`

Remember: Jira is the single source of truth. Local folders and files are synchronized FROM Jira, not TO Jira (except for user story imports).

Jira Synchronization System Guide

Jira Synchronization System Guide

Overview

Architecture

Components

1. Commands (User Interface)

2. Product Manager Agent (Orchestrator)

3. Jira Skills (Specialized Workers)

a) folder-sync.md

b) stories-sync.md

c) phase-management.md

d) archive-handler.md

Common Workflows

Workflow 1: Daily Sync

Workflow 2: Working on Specific Epic

Workflow 3: Initiative Planning

Workflow 4: Cleanup Closed Work

Workflow 5: Phase Management

Folder Structure

sync-manifest.json Structure

stories.json Structure

Naming Conventions

Initiatives

Epics

Archived Epics

Phases

Best Practices

Daily Operations

Safety

Performance

Conflict Resolution

Troubleshooting

Problem: Sync fails with “Epic not found”

Problem: Folder structure out of sync

Problem: stories.json has conflicts

Problem: Archive operation failed

Advanced Usage

Custom Sync Workflows

Integration with Other Commands

Related Documentation

Quick Reference Card