feat: add GitHub Issues Integration extension

[Fatima367]

Summary

Adds a community extension that generates spec artifacts from GitHub Issues, eliminating
duplicate work between issue tracking and Specification-Driven Development (SDD).

Resolves #2175

Problem

Developers already document requirements in GitHub Issues (user stories, acceptance criteria,
labels, discussions) but then rewrite everything from scratch in spec.md when starting SDD.
This creates:

• Duplicate work - Writing the same information twice
• Context loss - Losing valuable discussion and rationale from issues
• Sync drift - Issues and specs diverge over time
• Manual overhead - Copying and reformatting content manually

Solution

This extension provides three commands that bridge GitHub Issues and Spec Kit:

Commands

1. /speckit.github-issues.import - Import a GitHub Issue and generate structured spec.md - Fetches issue title, body, labels, and comments

   • Parses structured sections (problem, solution, alternatives)
   • Generates spec with requirements and acceptance criteria
   • Creates metadata for tracking

2. /speckit.github-issues.sync - Keep specs updated when source issues change

   • Detects changes in linked issues
   • Updates spec with latest issue data
   • Appends new comments to Discussion Notes
   • Maintains sync timestamps

3. /speckit.github-issues.link - Add bidirectional traceability

   • Links spec to source issue
   • Posts comment on GitHub Issue linking back to spec
   • Creates metadata file for tracking

Features

• ✅ Import GitHub Issues to structured spec.md files
• ✅ Structured parsing of problem statements, solutions, acceptance criteria
• ✅ Preserve valuable comments and context
• ✅ Bidirectional links between issues and specs
• ✅ Automatic sync when issues change
• ✅ Label integration as spec tags
• ✅ Issue state tracking (open/closed)

Extension Details

• Extension ID: github-issues
• Version: 1.0.0
• Category: integration
• Effect: Read+Write
• License: MIT
• Author: @Fatima367

Prerequisites

• GitHub CLI (gh) installed and authenticated
• Read access to target repositories
• Write access for bidirectional linking (optional)

Installation

After this PR is merged, users can install the extension from the main spec-kit repository:

# Install from local spec-kit directory
specify extension add --dev /path/to/spec-kit/spec-kit-github-issues

For testing this PR before merge:

# Clone the PR branch
git clone -b add-github-issues-extension https://github.com/Fatima367/spec-kit.git
cd spec-kit

# Install the extension
cd /path/to/your-project
specify extension add --dev /path/to/spec-kit/spec-kit-github-issues

## Testing

Tested locally with issue #2175:
- ✅ Successfully imported issue and generated spec.md
- ✅ Created proper metadata files
- ✅ Extension manifest validates correctly

##  Files Added:

- spec-kit-github-issues/extension.yml - Extension manifest
- spec-kit-github-issues/commands/import.md - Import command
- spec-kit-github-issues/commands/sync.md - Sync command
- spec-kit-github-issues/commands/link.md - Link command
- spec-kit-github-issues/README.md - Documentation
- spec-kit-github-issues/CHANGELOG.md - Version history
- spec-kit-github-issues/LICENSE - MIT License
- spec-kit-github-issues/github-issues-config.template.yml - Config template
- spec-kit-github-issues/.extensionignore - Ignore patterns

##  Checklist

- Valid extension.yml manifest
- Complete README with installation and usage instructions
- LICENSE file included (MIT)
- CHANGELOG.md with version history
- All commands working as documented
- Extension tested on a real project
- Command names follow speckit.{ext-id}.{command} pattern
- No old command references remaining
- Configuration template provided

## Next Steps

After this PR is merged:
1. The extension will be available in the main spec-kit repository at `spec-kit-github-issues/` 
2. Users can install it locally using `specify extension add --dev`
3. A follow-up PR can add this extension to the Community Extensions table in the main README   

**Note:** This extension is bundled with the main spec-kit repository. For a standalone
community extension, it would need to be moved to a separate repository with GitHub releases.
## Testing Screenshots

Successfully imported issue #2175 and generated spec:
- Created .specify/specs/001-generate-spec-artifacts-from-github-issues/spec.md
- Created .specify/specs/001-generate-spec-artifacts-from-github-issues/.issue-link
- Parsed 3 user stories with acceptance criteria
- Preserved discussion notes from comments

[Copilot]

Pull request overview

Adds a new “GitHub Issues Integration” community extension intended to generate and sync Spec Kit spec artifacts from GitHub Issues (import/sync/link) to reduce duplicate effort between issue tracking and SDD.

Changes:

• Introduces a new extension manifest (extension.yml) with three commands: import, sync, and link.
• Adds command documentation/workflows for importing issues into specs, linking specs ↔ issues, and syncing updates.
• Adds extension packaging/documentation assets (README, config template, changelog, license, ignore rules).

Show a summary per file

File	Description
spec-kit-github-issues/extension.yml	Defines the extension metadata, requirements, and command registrations.
spec-kit-github-issues/commands/import.md	Documents the import workflow (fetch issue data, parse, generate spec + metadata).
spec-kit-github-issues/commands/sync.md	Documents syncing linked specs from issue updates (detect + apply updates).
spec-kit-github-issues/commands/link.md	Documents bidirectional linking (update spec + comment back on issue).
spec-kit-github-issues/github-issues-config.template.yml	Provides configurable defaults for repository/import/sync/link behavior.
spec-kit-github-issues/README.md	End-user installation, usage, troubleshooting, and examples.
spec-kit-github-issues/CHANGELOG.md	Initial release notes and (currently external) release link.
spec-kit-github-issues/LICENSE	Adds MIT license text for the extension.
spec-kit-github-issues/.extensionignore	Defines excluded files for extension installation packaging.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (6)

spec-kit-github-issues/commands/import.md:94

• These sed regexes use \s to match whitespace, but POSIX/BSD/GNU sed basic regular expressions don’t support \s (it’s treated as a literal s). This will fail to extract the intended sections from the issue body. Use [[:space:]] (or another portable approach) for whitespace matching, and consider a more robust parser to avoid brittle section slicing.

# Parse sections from issue body
problem=$(echo "$body" | sed -n '/^[#*]*\s*Problem/,/^[#*]*\s*[A-Z]/p' | sed '$d' | sed '1d')
solution=$(echo "$body" | sed -n '/^[#*]*\s*[Pp]roposed [Ss]olution/,/^[#*]*\s*[A-Z]/p' | sed '$d' | sed '1d')
alternatives=$(echo "$body" | sed -n '/^[#*]*\s*[Aa]lternative/,/^[#*]*\s*[A-Z]/p' | sed '$d' | sed '1d')

**spec-kit-github-issues/commands/link.md:94**
* This command searches for specs under `.specify/specs`, but Spec Kit’s core workflow uses `specs/` for feature directories (see `templates/commands/specify.md`). As written, linking will fail in a standard project layout. Recommend updating to `specs/` and/or reading `.specify/feature.json` to reliably locate the current feature directory.

Determine current feature directory

current_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)

if [[ "$current_branch" =~ ^[0-9]+-(.+)$ ]]; then

Extract feature name from branch

feature_pattern="${current_branch}"
feature_dir=$(find .specify/specs -maxdepth 1 -type d -name "$feature_pattern" | head -1)
else

Use most recent feature directory

feature_dir=$(ls -td .specify/specs/*/ 2>/dev/null | head -1)
fi

**spec-kit-github-issues/commands/sync.md:41**
* This sync workflow assumes specs live under `.specify/specs/*`, but Spec Kit’s core feature directories default to `specs/` (per `templates/commands/specify.md`). That mismatch means sync won’t discover `.issue-link` files or specs in typical projects. Recommend switching discovery to `specs/*/.issue-link` and/or using `.specify/feature.json` to find the active feature directory.

# Find all .issue-link files
linked_specs=()
for link_file in .specify/specs/*/.issue-link; do
  if [ -f "$link_file" ]; then
    linked_specs+=("$link_file")
  fi
done

spec-kit-github-issues/commands/sync.md:124

• This writes update candidates to a fixed /tmp/specs_to_update.txt without clearing it first. If the file exists from a prior run, stale entries can be reprocessed. Also, using a fixed path can cause collisions across concurrent runs. Recommend creating a fresh temp file via mktemp, truncating it at the start, and ensuring cleanup via trap.

  if [[ "$updated_at" > "$last_synced" ]] || [ -z "$last_synced" ]; then
    echo "  ✓ Updates detected (last synced: $last_synced, updated: $updated_at)"
    
    # Store for processing
    echo "$feature_dir|$repo|$issue_number|$spec_file" >> /tmp/specs_to_update.txt
  else

spec-kit-github-issues/commands/sync.md:195

• last_synced is used to filter new comments here, but it isn’t set anywhere in this while read ... loop (it was only read in the earlier “Check for Updates” loop). This will cause incorrect filtering (likely using a stale value). Re-read last_synced from "$feature_dir/.issue-link" inside this loop, or include it as an additional field in the temp file and read it back with the other columns.

  # Append new comments to Discussion Notes section
  new_comments=$(echo "$issue_data" | jq -r --arg last_synced "$last_synced" \
    '.comments[] | select(.createdAt > $last_synced) | "**\(.author.login)** (\(.createdAt)):\n\(.body)\n"')
  

spec-kit-github-issues/commands/sync.md:183

• These sed -i replacements are both non-portable (BSD/macOS sed requires a different -i usage) and the regex patterns don’t correctly escape the literal ** in **Issue Status:** / **Labels:** / **Last Updated:**. As a result, the replacements may not match/update the spec. Recommend using a portable edit approach (e.g., write to a temp file then mv) and escape the asterisks (^\*\*Issue Status:\*\*).

  # Update spec frontmatter
  sed -i "s|^**Issue Status:**.*|**Issue Status:** $state|" "$spec_file"
  sed -i "s|^**Labels:**.*|**Labels:** $labels|" "$spec_file"
  sed -i "s|^**Last Updated:**.*|**Last Updated:** $(date -u +"%Y-%m-%d")|" "$spec_file"

• Files reviewed: 9/9 changed files
• Comments generated: 8

[Copilot]

The command frontmatter tools: is for MCP tool identifiers; bash/gh isn’t a documented/used MCP tool in this repo. Since the workflow uses the local gh CLI, remove tools: or replace it with the actual MCP tool ID (if one exists).

This issue also appears in the following locations of the same file:

• line 34
• line 119
• line 180
• line 192

Suggested change

	tools:
	- 'bash/gh'

[Copilot]

The installation instructions use --from https://github.com/Fatima367/spec-kit-github-issues/... (a standalone repo release). But this PR adds the extension inside the github/spec-kit monorepo, and there’s no catalog entry here for github-issues. Recommend updating the README to match the intended distribution model (e.g., specify extension add --dev /path/to/spec-kit/spec-kit-github-issues for this repo layout, or add a catalog entry / move it under extensions/github-issues/ if it’s meant to be bundled/installable by name).

[Copilot]

extension.repository points to https://github.com/Fatima367/spec-kit-github-issues, but the extension is being added to the github/spec-kit repo in this PR. This mismatch can confuse users and tooling that expects the repository URL to match the installed source. Recommend either (a) updating repository/homepage to the github/spec-kit location (possibly the subdirectory), or (b) moving this extension to the referenced standalone repo and consuming it via catalog/URL.

[Copilot]

The changelog links [1.0.0] to a release tag in Fatima367/spec-kit-github-issues, but this PR is adding the extension code into github/spec-kit. If the extension isn’t actually released from that standalone repo, this link will be incorrect for users. Recommend pointing the link at the correct release location (or removing the link until a release exists).

Suggested change

	[1.0.0]: https://github.com/Fatima367/spec-kit-github-issues/releases/tag/v1.0.0

[mnriem]

Please address Copilot feedback. If not applicable, please explain why

[mnriem]

Note community extensions are self-hosted as per https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md