Tighter integration between GitHub Issues and Spec Kit created branches

[ahmadabdalla]

Overview

Enhance Spec Kit with native GitHub issue integration to create better traceability and enable issue-driven specification workflows.

Current Behavior

Today, the Spec Kit workflow operates as follows:

1. Run /speckit.specify with a description
2. Spec Kit creates a feature branch
3. Work on the specification
4. Raise a PR against main
5. Merge after review

The Problem: There's no connection to GitHub issues, so:

• No automatic issue tracking
• Manual effort to link specs to issues
• Missing context from existing issue discussions
• Harder to trace specs back to original requirements

Suggestion

New /speckit.issue Command

Add a new /speckit.issue command that:

1. Searches for existing issues based on user input text

   • Checks the repository for matching issues
   • Displays relevant matches for selection

2. Prompts issue creation if no matching issue exists

   • Guides user through creating a well-structured issue

3. Leverages /speckit.clarify during issue creation to:

   • Categorize the issue type (feature, bug, enhancement, documentation, etc.)
   • Add structured context and details
   • Improve clarity of the issue description
   • Ensure all necessary information is captured

4. Returns a GitHub issue URL for use in subsequent commands

As is /speckit.specify Command

Run /speckit.specify and pass the GitHub issue URL:

• Automatically pull context from the issue
• Use issue title/description to populate spec metadata
• Create feature branch with issue number in the name (e.g., spec/123-feature-name)
• Link the spec to the GitHub issue
• Continue with existing spec generation workflow (e.g. clarify .. )

New /speckit.pullrequest Command

Add a new /speckit.pullrequest command that:

1. Detects the associated GitHub issue from the current branch

   • Reads issue number from branch name (e.g., spec/123-feature-name → issue #1234567)
   • Falls back to stored metadata from /speckit.specify

2. Creates a pull request with smart defaults:

   • PR title pulled from the issue title
   • PR description includes:
     • Link to the associated issue (e.g., "Closes #1234567" or "Fixes #1234567")
     • Summary of changes from the implemented plan.
     • Any additional context

3. Automatically links the PR to the issue:

   • Uses GitHub keywords (Closes, Fixes, Resolves) to auto-close issue on merge
   • Adds PR reference to the issue timeline

4. Optional parameters:

   • Custom PR title/description
   • Target branch (defaults to main)
   • Draft PR flag
   • Reviewers assignment

Suggested User Flow

Complete Workflow: Issue → Spec → PR

/speckit.issue "Add user authentication feature"
  ↓ (searches GitHub for existing issues about authentication)
  ↓ (no match found)
  ↓ (runs /speckit.clarify to improve the issue description)
  ↓ (creates GitHub issue #1234567)
  ↓ (returns: "Created issue #1234567: https://github.com/org/repo/issues/123")
  
/speckit.specify https://github.com/org/repo/issues/123
  ↓ (pulls context from issue #1234567)
  ↓ (creates branch: spec/123-user-authentication)
  ↓ (generates spec with issue context)
  
[Work on your specification...]
  
/speckit.pullrequest
  ↓ (detects issue #1234567 from branch name)
  ↓ (creates PR with title from issue #1234567)
  ↓ (adds "Closes #1234567" to PR description)
  ↓ (links PR to issue automatically)
  ✅ PR created and ready for review!

Benefits

1. Full Traceability: Complete lifecycle from issue → spec → PR, all tightly linked
2. Better Documentation: Issues are clarified and improved before spec work begins
3. Reduced Duplication: Search prevents creating duplicate issues for the same work
4. Context Preservation: Issue discussions and requirements flow into the spec and PR
5. Automated Linking: PR automatically references and closes the associated issue
6. Project Management: Easy to track entire workflow through GitHub's native tools
7. Team Collaboration: Team members can follow the entire journey from idea to implementation
8. Zero Manual Linking: No need to manually add "Closes #1234567" or link issues to PRs

[amehmeto]

I've just downloaded and tried SpecKit, this is the first thing in my mind : how to integrate it with Github Issues and Github Projects

[mplevine]

Agreed! In fact, I'd like to be able to have the option to leverage the fantastic functionality in spec kit to help me specify an issue (e.g. a new feature), clarify it, plan it and break it down into tasks -- and then have it create an organized set of issues in GitHub that I can then assign to the Copilot agent to implement.

[lujmo11]

i asked deepwiki and it suggested .

To modify the spec-kit system to use GitHub Issues for task description and tracking instead of the current tasks.md approach, you can leverage the existing /speckit.taskstoissues command and modify the implementation workflow.

Current System vs GitHub Issues Integration

The current system generates tasks in tasks.md files with checkbox tracking, while GitHub Issues would provide centralized task management with labels, assignments, and status tracking.

Implementation Approach

1. Use the Existing /speckit.taskstoissues Command

The spec-kit already includes a command template for converting tasks to GitHub issues 1 :

/speckit.taskstoissues

This command:

• Validates prerequisites using the same script as other commands
• Extracts the Git remote URL to ensure issues are created in the correct repository
• Uses the GitHub MCP server to create issues from the task list
• Only creates issues if the remote is a GitHub URL (security measure)

2. Modified Workflow

Instead of the current workflow:

/speckit.tasks        # Generate tasks.md
/speckit.implement    # Execute and track in tasks.md

Use the GitHub Issues workflow:

/speckit.tasks           # Generate tasks.md
/speckit.taskstoissues   # Convert to GitHub Issues
/speckit.implement       # Execute, tracking via GitHub Issues

3. Task Structure Compatibility

The current task format in templates/tasks-template.md 2 is already compatible:

• Tasks have IDs (T001, T002, etc.)
• Descriptions include file paths
• Parallel execution markers [P]
• User story labels [US1], [US2], etc.

This structure maps well to GitHub Issues with:

• Issue titles from task descriptions
• Issue bodies containing file paths and context
• Labels for parallel tasks and user stories
• Issue numbers replacing task IDs

4. Implementation Tracking Modifications

To track progress via GitHub Issues instead of markdown checkboxes, modify /speckit.implement 3 to:

• Query GitHub Issues instead of parsing tasks.md
• Update issue status (close issues) instead of marking [X]
• Use GitHub Issue API for progress tracking
• Maintain issue comments for implementation details

5. Benefits of GitHub Issues Integration

• Centralized Tracking: All task management in GitHub's native system
• Team Collaboration: Assignees, mentions, and discussions
• Automation: GitHub Actions can trigger on issue status changes
• Visibility: Stakeholders can view progress without accessing codebase
• Integration: Links to PRs, branches, and commits

Notes

• The /speckit.taskstoissues command requires the GitHub MCP server tool 4
• Security measures ensure issues are only created in repositories matching the Git remote URL 5
• The existing task generation logic in /speckit.tasks 6 doesn't need modification - it creates the structured task list that gets converted to issues
• You can maintain both tasks.md and GitHub Issues in parallel during transition

Wiki pages you might want to explore:

• /speckit.implement Command (github/spec-kit)

Citations

File: templates/commands/taskstoissues.md (L1-31)

---
description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
tools: ['github/github-mcp-server/issue_write']
scripts:
  sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
  ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
---

## User Input

```text
$ARGUMENTS

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

Outline

1. Run {SCRIPT} from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").
2. From the executed script, extract the path to tasks.
3. Get the Git remote by running:

git config --get remote.origin.url

ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL

1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.

**File:** templates/tasks-template.md (L15-20)
```markdown
## Format: `[ID] [P?] [Story] Description`

- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
- Include exact file paths in descriptions

File: templates/commands/implement.md (L122-129)

8. Progress tracking and error handling:
   - Report progress after each completed task
   - Halt execution if any non-parallel task fails
   - For parallel tasks [P], continue with successful tasks, report failed ones
   - Provide clear error messages with context for debugging
   - Suggest next steps if implementation cannot proceed
   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.

File: templates/commands/tasks.md (L70-106)

## Task Generation Rules

**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.

**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.

### Checklist Format (REQUIRED)

Every task MUST strictly follow this format:

```text
- [ ] [TaskID] [P?] [Story?] Description with file path

Format Components:

1. Checkbox: ALWAYS start with - [ ] (markdown checkbox)
2. Task ID: Sequential number (T001, T002, T003...) in execution order
3. [P] marker: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
4. [Story] label: REQUIRED for user story phase tasks only
   • Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
   • Setup phase: NO story label
   • Foundational phase: NO story label
   • User Story phases: MUST have story label
   • Polish phase: NO story label
5. Description: Clear action with exact file path

Examples:

• ✅ CORRECT: - [ ] T001 Create project structure per implementation plan
• ✅ CORRECT: - [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py
• ✅ CORRECT: - [ ] T012 [P] [US1] Create User model in src/models/user.py
• ✅ CORRECT: - [ ] T014 [US1] Implement UserService in src/services/user_service.py
• ❌ WRONG: - [ ] Create User model (missing ID and Story label)
• ❌ WRONG: T001 [US1] Create model (missing checkbox)
• ❌ WRONG: - [ ] [US1] Create User model (missing Task ID)
• ❌ WRONG: - [ ] T001 [US1] Create model (missing file path)

[chriso0710]

Tighter github integration would be great!

Here is my workflow at the moment, using Claude code:

1. Usually I let Claude create issues for me on github. But only specs, without technical details, since these are in the constitution.
2. I run specify with mentioning the issue like this
   /speckit.specify look into issue #4711 and use it as input for the specification
3. After planning and implementing I close the issue manually.

ATM this works pretty good for me...

[chriso0710]

also see #935 for some interesting suggestions