---
description: TaskMaster -> GitHub Issue Sync
---

# TaskMaster -> GitHub Issue Sync

Reads TaskMaster's tasks.json and automatically creates GitHub Issues and Milestones.

**Important - ID Distinction:**
- **GitHub Issue**: `#1`, `#2` (auto-assigned by GitHub, sequential)
- **TaskMaster Task ID**: `task 1`, `task 2` (based on tasks.json)
- **After sync**: Issue body contains `Task Master Reference: task N` for mapping

Follow the project guidelines in `@CLAUDE.md`.

---

## Structure Design

```
GitHub                          TaskMaster
──────                          ──────────
Milestone: Phase 1 MVP    ←──   PRD Phase 1 (Task 1-4)
├── Issue #1              ←──   task 1 (main task)
├── Issue #2              ←──   task 2
├── Issue #3              ←──   task 3
└── Issue #4              ←──   task 4

Milestone: Phase 2 Core   ←──   PRD Phase 2 (Task 5-7)
├── Issue #5              ←──   task 5
...
```

**Principles:**
- **Milestone** = PRD Phase unit (count varies by PRD)
- **Issue** = Main task unit (pending/in-progress status only)
- **Subtask** = Checkbox in Issue + TaskMaster internal management
- **done status tasks** = Excluded from sync

---

## Workflow Steps

### 1. Pre-checks

```bash
# Verify tasks.json exists
ls .taskmaster/tasks/tasks.json

# Check repository labels
gh label list

# Check existing milestones
gh milestone list

# Check existing Issues (for number prediction)
gh issue list --state all --limit 1 --json number
# Example: [{"number": 5}] → Next Issue starts from #6

# Check if TaskMaster-related Issues already exist
gh issue list --search "in:body \"Task Master Reference\"" --state all --json number,title
```

**Issue Number Prediction:**
```
Current max Issue number: #5
→ task 1 = Issue #6
→ task 2 = Issue #7
→ ...
→ task 12 = Issue #17

(Note: PRs use same number pool, so creating PR in between shifts numbers)
```

### 2. Analyze tasks.json and PRD

```bash
# Check task list
task-master list
```

**PRD Phase Mapping (requires dynamic verification):**

Before execution, verify sync target tasks with these commands:

```bash
# Query only pending/in-progress tasks (exclude done)
task-master list --status pending
task-master list --status in-progress

# Or check status from full list
task-master list
```

**Phase Mapping Method:**
1. Check Phase structure from the relevant PRD file (`.taskmaster/docs/`)
2. Verify actual Task ID range from `task-master list` results
3. Create mapping table using template below

| Phase | TaskMaster Task IDs | Description |
|-------|---------------------|-------------|
| [PRD Phase name] | task N, N+1, ... | [From PRD] |
| ... | ... | ... |

**Note - Version-based Milestone Prefix:**
- Existing v1 PRD tasks: `Phase 1: MVP`, `Phase 2: Core`, etc.
- v2+ PRD tasks: Recommended to differentiate with `V2 Phase 1: ...`, `V3 Phase 1: ...`

### 3. Establish Conversion Plan and Get User Confirmation

Output conversion plan in this format and **require user confirmation**:

```
[PRD Information]
- File: .taskmaster/docs/<prd-filename>.md
- Version: V2 (or applicable version)

[Sync Target Tasks]
- Task ID Range: N ~ M (pending/in-progress status)
- Total Tasks: X

[Milestone Creation Plan] (by Phase count)
- [Version] Phase 1: [Name] (includes task N-M)
- [Version] Phase 2: [Name] (includes task N-M)
- ...

[Issue Creation Plan] (by task count)
[Version] Phase 1 children:
  - Issue: [type] task N - [task title]
  - Issue: [type] task N+1 - [task title]
  ...
```

### 4. Create Milestones

Create Milestones by Phase:

```bash
# Phase 1
gh api repos/:owner/:repo/milestones \
  -f title="Phase 1: MVP" \
  -f description="Initial setup, design system, layout, auth implementation (task 1-4)"

# Phase 2
gh api repos/:owner/:repo/milestones \
  -f title="Phase 2: Core Features" \
  -f description="Dashboard, VLM analysis, VLM-CoT analysis implementation (task 5-7)"

# Phase 3, 4 similarly...
```

### 5. Create Issues

Convert main Tasks to Issues:

#### Title Format
`[Type] Concise work description`

#### Label Selection (use actual repository labels)
**Note**: Only use labels that actually exist from `gh label list` results

Examples (varies by project):
- **Type**: `type: feature`, `type: enhancement`, `type: bug`, `type: refactor`
- **Area**: `frontend`, `backend`, `api`, `ai`, `infrastructure`
- **Complexity**: `complexity: easy`, `complexity: medium`, `complexity: hard`

#### Body Template

**Important**: `Task Master Reference` section must be included (used for mapping in resolve-issue)

```markdown
## Purpose
[Extract from Task description]

## Work Items
[Convert details field to checkboxes]
- [ ] Specific requirement 1
- [ ] Specific requirement 2
- [ ] Specific requirement 3

## Files to Modify
[Extract file paths from details field, or "TBD during implementation"]
- `path/filename` - Change description

## Technical Details
[Code examples or detailed content from details field]

## Completion Criteria
[Extract from testStrategy field]
- [ ] Test condition 1
- [ ] Test condition 2

## Dependencies
[Convert dependencies field → GitHub Issue numbers]
- Prerequisites: #N (task M) or "None"

## References (optional)
[Add related PRs or docs if any, otherwise omit section]
- Related PR: #N - description
- Documentation: [link]

---
**Task Master Reference**: task [TASK_ID]
```

**Example (for task 1):**
```markdown
## Purpose
Create Next.js 15 App Router based project in frontend/ directory and set up core dependencies.

## Work Items
- [ ] Create project with create-next-app
- [ ] Initialize Shadcn/ui
- [ ] Install required dependencies (next-themes, framer-motion, etc.)
- [ ] Configure Pretendard font
- [ ] Customize tailwind.config.ts
- [ ] Set up ESLint/Prettier

## Files to Modify
- `frontend/` - New directory creation
- `frontend/tailwind.config.ts` - Custom settings
- `frontend/app/layout.tsx` - Pretendard font configuration

## Completion Criteria
- [ ] npm run dev runs successfully
- [ ] npm run build succeeds
- [ ] localhost:3000 accessible

## Dependencies
- None

---
**Task Master Reference**: task 1
```

#### Issue Creation Command
```bash
gh issue create \
  --title "[type] title" \
  --body "body content" \
  --label "label1,label2" \
  --milestone "milestone-name"
```

### 6. Connect Dependencies and Record ID Mapping

**Issue Creation Order**: Create sequentially starting from lowest ID among sync target tasks

| TaskMaster ID | GitHub Issue | Title |
|---------------|--------------|-------|
| task N | #X | [task title] |
| task N+1 | #X+1 | [task title] |
| ... | ... | ... |

**Dependency Conversion:**
- Dependencies within sync targets: "Prerequisites: #X (task N)" in Issue body
- Dependencies on done status tasks: "Prerequisites: task N (completed)" in Issue body - no GitHub Issue

### 7. Report Results and Output Mapping Table

**Important**: Create mapping table with actual Issue numbers created (based on numbers predicted in pre-check)

```
[Sync Complete]

PRD: .taskmaster/docs/<filename>.md
Version: [V1/V2/...]

Milestones ([count]):
- [Version] Phase 1: [Name]
- [Version] Phase 2: [Name]
- ...

Issues ([count]):
| GitHub Issue | TaskMaster | Title | Milestone |
|--------------|------------|-------|-----------|
| #X | task N | [task title] | [Version] Phase 1: [Name] |
| #X+1 | task N+1 | [task title] | [Version] Phase 1: [Name] |
| ... | ... | ... | ... |

(X = existing max Issue/PR number + 1, N = starting Task ID of sync targets)
```

**Post-creation Verification:**
```bash
# Check actually created Issues
gh issue list --state open --json number,title --limit 20

# Verify mapping
gh issue view <number> --json body | grep "Task Master Reference"
```

**Next Step Guide:**
```
Next step: /tm:resolve-issue <GitHub Issue number> or /tm:resolve-issue task 1
```

---

## Option Handling

### Arguments
- ARGUMENTS empty: All sync target Tasks (pending/in-progress status)
- ARGUMENTS is Phase number: That Phase only (e.g., phase1, 1, v2-phase1)
- ARGUMENTS is Task ID: Those Tasks only (e.g., task 11, 11,12,13)

### Status Filter
- Only sync pending, in-progress status
- Skip done, cancelled

---

> See [Work Guidelines](../guidelines/work-guidelines.md)

### Korean Encoding Notes

**Issue**: Korean characters in `gh issue create --title` command sometimes break into `\uXXXX` unicode escapes

**Workaround**: After Issue creation, check if title is broken, and fix with `gh issue edit` if so

```bash
# Check title after Issue creation
gh issue list --state open --limit 10 --json number,title

# Fix if title is broken
gh issue edit <number> --title "[bugfix] Fix dark mode video play button color"
```

**Checkpoint**: Must verify titles with `gh issue list` after all Issues are created

---

## Cautions

1. **Prevent Duplicate Creation**

   Always check existing Issues before sync:

   ```bash
   # Check full Issue list
   gh issue list --state all --limit 100

   # Search if specific task already has Issue
   gh issue list --search "Task Master Reference: task 1" --state all

   # Or search by body content
   gh issue list --search "in:body \"Task Master Reference\"" --state all
   ```

   **If already exists**: Skip that task and notify user

2. **User Confirmation Required**
   - Must confirm plan before Milestone/Issue creation
   - Ask about label creation if labels don't exist

3. **Maintain ID Mapping Records**
   - Output mapping table after sync completion
   - Referenced in resolve-issue later

---

> See [ID Reference](../guidelines/id-reference.md)
