Spec-Kit Tasks to Issues

Convert tasks.md into GitHub issues with proper dependencies, labels, and organization. Optional step after speckit-tasks for teams using GitHub project management.

When to Use

• After creating tasks.md with speckit-tasks
• Team uses GitHub Issues for task tracking
• Want to leverage GitHub Projects, milestones, or automation
• Need to assign tasks to team members

Execution Workflow

🚨 CRITICAL SAFETY REQUIREMENT 🚨

MUST verify GitHub remote URL BEFORE creating ANY issues!

• ONLY proceed if remote is a valid GitHub URL
• NEVER create issues in the wrong repository
• ALWAYS confirm repository matches your intent

1. Setup: Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks to get FEATURE_DIR and AVAILABLE_DOCS, extract path to tasks file

2. CRITICAL SAFETY CHECK - Verify GitHub remote:

   git config --get remote.origin.url
   

   ONLY proceed if:

   • URL contains github.com
   • Repository matches intended target
   • You have write permission

   NEVER create issues in wrong repository!

3. Parse tasks from tasks.md - Extract:

   • Task ID (T001, T002, etc.)
   • Description with file path
   • Phase (Setup, Foundation, User Story X)
   • User Story label ([US1], [US2], etc.)
   • Parallel marker ([P])
   • Dependencies (from task order and phase structure)

4. Create issues - For each task, use GitHub MCP server:

   • Title format: [T001] Task description from tasks.md

   • Body:

     **Phase:** [Phase Name]
     **Story:** [US1] or N/A
     **File:** [Specific file path from task]
     **Parallelizable:** Yes/No
     
     ## Description
     
     [Full task description]
     
     ## Dependencies
     
     [List of blocking tasks with issue links]
     
     ## Acceptance Criteria
     
     [Extracted from tasks.md or generated]
     
     ## Related Artifacts
     
     - Spec: [link to spec.md on branch]
     - Plan: [link to plan.md on branch]
     - Tasks: [link to tasks.md on branch]
     
     ---
     
     _Feature:_ [Feature Name]
     _Task ID:_ [T001]
     _Generated by speckit-taskstoissues_
     

   • Metadata:

     • Labels: phase:setup, feature:[name], task, parallel (if [P])
     • Milestone: Feature milestone (if exists)
     • Assignee: None (unless specified)

5. Link dependencies:

   • Option A - Task Lists (recommended): Add to issue body: ## Blocked By\n- [ ] #123 (T004 Create User model)
   • Option B - Issue References: Use Depends on #123, #124
   • Option C - Labels: blocked / ready

6. Organization:

   • Create milestones per user story
   • Apply labels by category (phase, parallel, test, feature)
   • Add to GitHub Project board if exists

Key Points

• Validate GitHub remote BEFORE creating any issues - NEVER skip this check
• Preserve task IDs in issue titles for mapping
• Link dependencies explicitly using task lists or references
• Use labels for organization - phase, parallel, test, feature, blocked, ready
• Include artifact links in issue body (spec, plan, tasks on branch)
• Create milestone per user story for organization
• Error handling:
  • Rate limiting → pause and retry
  • Permission denied → abort with clear error
  • Duplicate detection → check existing issues first
• Safety checks before ANY issue creation:
  • Verify remote is GitHub URL
  • Extract owner/repo correctly
  • Confirm with user before proceeding

Next Steps

After creating issues:

• Assign issues to team members
• Organize in GitHub Project board
• Track progress via issue updates
• Link PRs to issues (closes #123)
• Update issue status as tasks complete

See Also

• speckit-tasks - Break plan into actionable tasks
• speckit-implement - Execute implementation plan