speckit-phasestoissues

name	speckit-phasestoissues
description	Convert development phases into individual GitHub issues for better tracking and collaboration.
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"workflows:commands/phasestoissues.md"}

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

1. Load Feature Context

Run the prerequisite check script from repo root and parse the output:

cd "$(git rev-parse --show-toplevel)" && \
source .specify/scripts/bash/common.sh && \
get_feature_paths

This provides:

• FEATURE_DIR - Feature directory path
• FEATURE_SPEC - Specification file (spec.md)
• IMPL_PLAN - Implementation plan (plan.md)
• TASKS - Task list (tasks.md)

All paths are absolute.

2. Verify GitHub Repository

Get the Git remote URL:

git config --get remote.origin.url

[!CAUTION] ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL

Stop immediately if:

• Remote is not a GitHub URL
• Remote URL cannot be determined
• Repository does not match expected pattern

3. Extract Phase Information

Load and parse the specification file ($FEATURE_SPEC / spec.md):

Extract:

• Phase Title: First H1 heading or feature name from directory
• Phase Description: Content under "Story" or "Overview" section
• Acceptance Criteria: Content under "Acceptance Criteria" section
• Context/Background: Any additional context sections

Parse Tasks from $TASKS (tasks.md):

• Extract all task lines in format: - [ ] T001: Task description
• Preserve task IDs and descriptions
• Note task status (pending vs completed)

Parse Plan (if exists) from $IMPL_PLAN (plan.md):

• Extract implementation approach
• Note technical decisions
• Identify dependencies

4. Build Phase Issue Body

Construct a comprehensive GitHub issue for each phase with this structure:

## Description

[Phase description from spec.md]

## Acceptance Criteria

[Acceptance criteria from spec.md]

## Implementation Plan

[High-level approach from plan.md, if available]

### Key Technical Decisions
- [Decision 1]
- [Decision 2]

### Dependencies
- [Dependency 1]
- [Dependency 2]

## Tasks

See sub-issues for individual task tracking.

## Context

**Branch**: `[branch-name]`
**Feature Directory**: `[feature-dir]`
**Phase**: [phase-number]/[total-phases]
**Created from spec-kit workflow**

---

**Note**: Sub-issues will be created for each task. Use `/speckit.workflows.review` to validate implementation against acceptance criteria.

5. Determine Issue Labels

Automatically assign labels based on:

Workflow Type (from branch pattern):

• bugfix/* -> bug, bugfix
• refactor/* -> refactor, technical-debt
• hotfix/* -> hotfix, urgent
• modify/* -> enhancement, modification
• deprecate/* -> deprecation, breaking-change
• Standard feature -> feature, enhancement

Priority (from spec.md if available):

• Critical/High -> priority: high
• Medium -> priority: medium
• Low -> priority: low

Status:

• status: planning (if tasks exist but none completed)
• status: in-progress (if some tasks completed)

6. Create Phase Issues

For each phase, use the GitHub MCP server tool to create the parent issue:

Required:

• owner: Extract from Git remote URL
• repo: Extract from Git remote URL
• title: "Phase N: [Phase title]" from spec.md
• body: Formatted issue body from step 4
• labels: Labels from step 5

Capture the issue number for sub-issue creation.

7. Create Sub-Issues for Tasks

For each task within a phase:

1. Create task issue using GitHub MCP:

   • title: "T001: [Task description]" (preserve task ID)
   • body:

     ## Task Details
     
     [Task description from tasks.md]
     
     ## Context
     
     **Parent Phase**: #[phase-issue-number]
     **Branch**: [branch-name]
     **Feature Directory**: [feature-dir]
     
     ---
     
     Part of larger feature spec-kit workflow.
     

   • labels: Same labels as parent phase issue

2. Link as sub-issue using mcp_github_github_sub_issue_write:

   • method: "add"
   • owner: From Git remote URL
   • repo: From Git remote URL
   • issue_number: Parent phase issue number
   • sub_issue_id: Task issue ID (not issue number - get from created issue)

Important: GitHub sub-issues require issue IDs, not issue numbers. Extract the id field from the created task issue.

8. Set Sub-Issue Priority

If tasks have natural ordering, use mcp_github_github_sub_issue_write with method "reprioritize" to set task order within the phase

• labels: Labels from step 5

[!CAUTION] UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL

Example:

Repository: github.com/user/repo
Title: Phase 1: User Authentication
Labels: feature, status: planning
Body: [Full formatted content]

9. Link Issue to Branch

After creating the issue, provide instructions to link it:

# Update spec.md with issue link
echo -e "\n## GitHub Issue\n\n#[issue-number]" >> "$FEATURE_SPEC"

# Or add issue number to commit messages
git commit --amend -m "feat: [phase title] (#[issue-number])"

10. Output Summary

Display result to user:

GitHub Issue Created

Issue: #[number]
Title: [phase title]
URL: https://github.com/[owner]/[repo]/issues/[number]

Tasks Included: [N tasks]
Labels: [label1, label2, ...]

Next Steps:
1. Review issue on GitHub
2. Assign to team members
3. Add to project board/milestone
4. Track progress by checking off tasks
5. Use /speckit.workflows.review when ready for validation

Important Notes

1. One Issue Per Phase: Creates a single issue representing the development phase
2. Tasks as Checkboxes: All tasks become checkboxes in the issue body
3. Comprehensive Context: Issue includes spec, acceptance criteria, and plan
4. Safe by Default: Validates GitHub remote before creating issues
5. Workflow Aware: Labels reflect the workflow type (bugfix, refactor, etc.)
6. Trackable: Issue provides full context for team discussion and tracking

Edge Cases

No tasks.md exists:

• Create issue with story and acceptance criteria only
• Note in issue body that task breakdown is needed
• Recommend running /speckit.tasks first

No spec.md exists:

• Cannot create issue without phase context
• Recommend running /speckit.plan or creating spec first
• Display error message with guidance

Multiple features in repo:

• Uses current feature based on branch/directory context
• Issue title and content scoped to current feature only

Issue already exists:

• Check if issue with same title exists (optional)
• Warn user before creating duplicate
• Offer to update existing issue instead

No GitHub remote:

• Stop with clear error message
• Cannot create issues without GitHub repository
• Suggest adding GitHub remote or creating issues manually

Context Information

User input: $ARGUMENTS

Create a comprehensive, well-structured GitHub issue that represents the development phase with tasks as actionable checkboxes.