GitHub Task Synchronisation

Synchronise task lists with GitHub Projects by creating issues and adding them to project boards.

When to Use This Skill

Use this skill when:

• User wants to add tasks to a GitHub project
• User has a task list (markdown, verbal, or structured) that should become GitHub issues
• User wants to sync a to-do list with their repository's project board
• User mentions "sync tasks", "add to project", "create issues from tasks", or similar phrases

Prerequisites Check

Before using this skill, verify:

1. gh CLI installation: Check if gh CLI is installed and authenticated

   gh auth status
   

   If not authenticated, inform user to run: gh auth login

2. Git repository: For auto-detection, ensure the user is in a git repository with a GitHub remote

Workflow

Step 1: Extract Tasks

Identify where tasks are coming from:

From markdown file with checkboxes:

- [ ] Implement user authentication
- [ ] Add database migrations
- [x] Set up CI/CD (skip completed)

From user message: "I need to add these tasks: implement login, fix bug #123, update documentation"

From structured data: User provides JSON or explicit list of tasks.

Parse tasks into a structured format. Each task needs:

• title (required): The task description
• body (optional): Additional details
• labels (optional): Array of label names

Step 2: Determine Target Repository

Check if user specified a repository:

• Explicit: "sync to myorg/myrepo"
• Implicit: User is working in a git repository

If not specified, attempt auto-detection:

# Use the sync_tasks.py script's auto-detection
# It checks 'origin' remote first, then falls back to first available remote

If auto-detection fails, ask user: "Which GitHub repository should these tasks be added to? (Format: owner/repo)"

Step 3: Determine Target Project

Check if user specified a project:

• Explicit: "add to project 3"
• Implicit: None specified

If not specified, use first available project:

# The script will automatically find the first project
# This works for most single-project repositories

If no projects exist, ask user: "No projects found for this repository. Would you like me to:

1. Create a new project
2. Specify a different project number
3. Just create the issues without adding to a project?"

Step 4: Execute Synchronisation

Run the sync script based on the task source:

For markdown file:

python3 scripts/sync_tasks.py --tasks-file /path/to/tasks.md [--repo owner/repo] [--project-number N]

For individual tasks:

python3 scripts/sync_tasks.py --task "Task 1" --task "Task 2" [--repo owner/repo] [--project-number N]

For JSON tasks:

python3 scripts/sync_tasks.py --json-tasks '[{"title":"Task 1","body":"Details"}]' [--repo owner/repo] [--project-number N]

Script behaviour:

• Auto-detects repo from git remotes if --repo not provided
• Auto-selects first project if --project-number not provided
• Creates GitHub issues for each task
• Adds issues to the specified project
• Returns JSON with results

Step 5: Report Results

Parse the script output and present results clearly:

results = {
  "success": true,
  "repo": "owner/repo",
  "project_number": 1,
  "synced_tasks": [
    {
      "task": {"title": "Task 1"},
      "issue_url": "https://github.com/owner/repo/issues/42"
    }
  ],
  "failed_tasks": []
}

Present to user:

• Success summary: "✅ Synced 3 tasks to owner/repo project #1"
• Links to created issues
• Any failures with reasons
• Next steps if applicable

Error Handling

gh CLI Not Authenticated

Error: gh CLI not installed or not authenticated

Action: Inform user to run gh auth login and offer to help with setup.

No Repository Found

Error: Could not determine GitHub repository

Action: Ask user to specify repository with --repo owner/repo or navigate to git repository.

No Projects Found

Error: No projects found for owner/repo

Action:

1. Verify repository exists and user has access
2. Check if projects exist via gh project list --owner OWNER
3. Offer to create issues without project, or help create project

Rate Limiting

If GitHub API rate limits are hit, inform user and suggest:

• Wait for rate limit reset
• Use authenticated requests (already done via gh CLI)
• Batch tasks if doing large syncs

Examples

Example 1: Sync markdown task list

User: "Sync the tasks in todos.md to my project"

1. Check gh auth status
2. Read and parse todos.md for - [ ] items
3. Detect repo from git remote (or ask if not found)
4. Run: python3 scripts/sync_tasks.py --tasks-file todos.md
5. Report: "✅ Created 5 issues and added them to project #1"

Example 2: Explicit repository and project

User: "Add these tasks to myorg/webapp project 2: fix login bug, update README"

1. Check gh auth status
2. Parse tasks from message
3. Run: python3 scripts/sync_tasks.py --task "Fix login bug" --task "Update README" --repo myorg/webapp --project-number 2
4. Report results with issue links

Example 3: No project specified

User: "Create issues for: refactor auth module, add tests"

1. Check gh auth status
2. Detect repo from git remote
3. Find first project (or ask if none)
4. Run sync with auto-detected parameters
5. Report results

Tips for Best Results

• Always verify authentication first - saves time if gh CLI needs setup
• Parse task titles concisely - keep titles under 80 characters when possible
• Use task bodies for details - move long descriptions to the body field
• Suggest labels when appropriate - e.g., "bug", "enhancement", "documentation"
• Handle completed tasks - skip [x] items in markdown lists
• Batch operations - sync multiple tasks in one script call for efficiency
• Provide clear feedback - users appreciate seeing what was created and where

Advanced: Custom Task Parsing

For complex task formats, parse them into the expected structure before calling the script:

tasks = [
    {
        "title": "Implement feature X",
        "body": "- Requirement 1\n- Requirement 2",
        "labels": ["enhancement", "priority:high"]
    }
]

Then pass via --json-tasks parameter.

Reference Documentation

For detailed gh CLI commands and GitHub Projects API patterns, see references/gh_cli_reference.md.