Skip to content
Trilogy Care Logo TC Docs

Jira Sync Guide

Jira Sync Guide

This directory contains all TC Portal initiatives and epics using a meta.yaml-based system synced from Jira.

📁 Structure

INITIATIVES/
├── TP-1857-Supplier-Management/
│   ├── meta.yaml                           # Initiative metadata
│   └── TP-2291-SAP-Supplier-Audit/         # Epic folder
│       ├── meta.yaml                       # Epic metadata + phases
│       ├── stories.yaml                    # User stories (synced from Jira)
│       ├── PROGRESS.md                     # Weekly progress notes
│       ├── idea.md                        # Original idea brief
│       ├── PRD.md                          # Product requirements
│       └── DUMP/                           # Attachments, exports

🔄 Syncing Commands

Product Manager agent uses /jira-sync with MCP Atlassian tools:

Terminal window
# Sync specific epic (daily)
/jira-sync --epic TP-432


# Sync entire initiative (weekly)
/jira-sync --initiative TP-1857


# Full sync (monthly)
/jira-sync --full

What Sync Does

  1. Fetches epic/initiative from Jira (getJiraIssue)
  2. Fetches phases: "parent = TP-432 AND type = Phase"
  3. Fetches stories: "parent = TP-432 AND type = Story"
  4. Creates/updates meta.yaml and stories.yaml files
  5. Creates PROGRESS.md template if missing
  6. Confirms with user before creating new epic folders

What Sync Skips

  • Archived epics (in ARCHIVED/ folders)
  • Tasks/subtasks (stay in Jira only)

📊 File Formats

Initiative meta.yaml

jira_key: TP-1857
title: Supplier Management
description: Initiative description from Jira
status: active
epic_count: 8
last_synced: 2025-01-10T14:30:00Z

Epic meta.yaml

jira_key: TP-432
title: S@H API
status: In Progress
prefix: SAH-API
description: Epic description from Jira
last_synced: 2025-01-10T14:30:00Z


phases:
  - key: TP-3020
    name: SAH-API - Discovery
    status: Done
    assignee:
      displayName: Sarah Chen
      accountId: acc1
    created: 2025-01-15T00:00:00Z

stories.yaml

epic_key: TP-432
last_synced: 2025-01-10T14:30:00Z
stories:
  - key: TP-2145
    title: As an API consumer, I want to authenticate via OAuth
    status: Done
    assignee: Alex Chen
    estimate: 8
    sprint: Sprint 23

🤖 For Product Manager Agent

Skills to Use

When syncing, invoke these skills in .claude/skills/:

  1. jira-full-sync - Orchestrate complete sync (initiatives → epics → phases → stories)
  2. initiative-epic-sync - Sync initiative/epic structure
  3. jira-phase-sync - Batch sync phases (1 query for all epics)
  4. stories-sync - Batch sync user stories (1 query for all epics)
  5. archive-handler - Archive closed epics with metadata

New Epic Discovery Flow

When you find epics in Jira that don’t exist locally:

1. Detect new epic (e.g., TP-2999)
2. Show user:
   "Found new epic: TP-2999 - New Feature Name
    Create local folder? [Y/n]"
3. If confirmed:
   - Create folder structure
   - Write meta.yaml
   - Write stories.yaml (if stories exist)
   - Create PROGRESS.md template
4. Append to SYNC-LOG.md

Logging

Append brief entries to .claude/INITIATIVES/SYNC-LOG.md:

## 2025-11-10 14:30
- Synced: 41 epics, 156 stories
- Created: 2 new epic folders (TP-2999, TP-3000)
- Archived: 1 closed epic
- Issues: None

Keep under 10 lines per sync.

📋 MCP Tools Used

Product Manager agent has access to:

  • mcp__atlassian__getJiraIssue - Get epic/initiative details
  • mcp__atlassian__searchJiraIssuesUsingJql - Batch query phases/stories
  • mcp__atlassian__getAccessibleAtlassianResources - Get cloud ID

Batch Query Strategy

Efficient approach (preferred):

// Single query for all phases
jql: "type = Phase AND parent IN (TP-432, TP-900, TP-901, ...)"


// Single query for all stories
jql: "type = Story AND parent IN (TP-432, TP-900, TP-901, ...)"

Performance: 144+ calls → 5 calls (97% reduction)

🛠️ Maintenance

Regular Tasks

  • Daily: Sync active epics with --epic
  • Weekly: Sync initiatives with --initiative
  • Monthly: Full sync with --full

Current State

  • 7 Active Initiatives with meta.yaml
  • 41 Active Epics with meta.yaml
  • 4 Archived Epics in ARCHIVED folders
  • System: meta.yaml-based (v2.0)

🔗 Resources

Last Updated: 2025-11-10 System: meta.yaml-based sync via MCP Atlassian tools