Migration Strategy

Backward Compatibility

Goal: Existing spec-kit projects work without changes.

Strategy:

1. Core commands unchanged: /speckit.tasks, /speckit.implement, etc. remain in core

2. Optional extensions: Users opt-in to extensions

3. Gradual migration: Existing taskstoissues stays in core, Jira extension is alternative

4. Deprecation timeline:

   • v0.2.0: Introduce extension system, keep core taskstoissues
   • v0.3.0: Mark core taskstoissues as "legacy" (still works)
   • v1.0.0: Consider removing core taskstoissues in favor of extension

Migration Path for Users

Scenario 1: User has no taskstoissues usage

• No migration needed, extensions are opt-in

Scenario 2: User uses core taskstoissues (GitHub Issues)

• Works as before
• Optional: Migrate to github-projects extension for more features

Scenario 3: User wants Jira (new requirement)

• specify extension add jira
• Configure and use

Scenario 4: User has custom scripts calling taskstoissues

• Scripts still work (core command preserved)
• Migration guide shows how to call extension commands instead

Extension Migration Guide

For extension authors (if core command becomes extension):

# Old (core command)
/speckit.taskstoissues

# New (extension command)
specify extension add github-projects
/speckit.github.taskstoissues

Migration alias (if needed):

# extension.yml
provides:
  commands:
    - name: "speckit.github.taskstoissues"
      file: "commands/taskstoissues.md"
      aliases: ["speckit.github.sync-taskstoissues"]  # Alternate namespaced entry point

AI agents register both names, so callers can migrate to the alternate alias without relying on deprecated global shortcuts like /speckit.taskstoissues.