π« Toolkit to help you get started with SDD or any other process!
Deprecate the core taskstoissues command (#4879)
rohanfa4b81dad128
diff --git a/docs/installation.md b/docs/installation.mdindex fa777a697..b68a65d24 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -147,14 +147,15 @@ After initialization, you should see the following commands available in your co- `/speckit.checklist` - Generate quality checklists- `/speckit.constitution` - Create or update project principles- `/speckit.converge` - Assess codebase against artifacts and append remaining tasks-- `/speckit.taskstoissues` - Convert tasks to issues (moving to the bundled `github` extension as+- `/speckit.taskstoissues` - Convert tasks to issues (deprecated; warns on invocation; replaced by the bundled `github` extension's`/speckit.github.taskstoissues`; install it with `specify extension add github`)The `generic` integration also registers extension commands in its configured`--commands-dir`. Installing `github` makes `/speckit.github.taskstoissues`available there as a command file, or as `/speckit-github-taskstoissues` when`--skills` is enabled. The core `/speckit.taskstoissues` (or-`/speckit-taskstoissues` with `--skills`) remains available.+`/speckit-taskstoissues` with `--skills`) remains available during migration, warns on invocation,+and will be removed in a future minor release.See the [GitHub extension's installation notes](https://github.com/github/spec-kit/blob/main/extensions/github/README.md#installation).Scripts are installed into a variant subdirectory matching the chosen script type:diff --git a/docs/reference/agentic-sdd.md b/docs/reference/agentic-sdd.mdindex 984c782c2..ea60858f3 100644--- a/docs/reference/agentic-sdd.md+++ b/docs/reference/agentic-sdd.md@@ -30,7 +30,7 @@ skills by default.| `/speckit.tasks` | `speckit-tasks` | Break the plan into actionable tasks || `/speckit.implement` | `speckit-implement` | Execute the tasks || `/speckit.converge` | `speckit-converge` | Assess implementation against the artifacts and append remaining work |-| `/speckit.taskstoissues` | `speckit-taskstoissues` | Optionally convert tasks into GitHub issues |+| `/speckit.taskstoissues` | `speckit-taskstoissues` | **Deprecated core command**; use the `github` extension for GitHub issues || `/speckit.clarify` | `speckit-clarify` | Resolve ambiguity before planning (optional quality gate; formerly `/quizme`) || `/speckit.analyze` | `speckit-analyze` | Check artifact consistency after tasks and before implementation (optional quality gate) || `/speckit.checklist` | `speckit-checklist` | Generate requirements-quality checklists (optional quality gate) |@@ -158,13 +158,24 @@ It first prints a severity-graded findings summary, then resolves to one of two- **Converged** β no gaps found. `tasks.md` is left byte-for-byte unchanged and you'll see a clean result like `β Converged β the implementation satisfies the spec, plan, and tasks.` You're done; proceed to review or open a PR.- **Tasks appended** β gaps found. Converge appends them as new tasks under a Convergence section in `tasks.md` and tells you how many. Run `/speckit.implement` again to complete them, then `/speckit.converge` once more. Each pass finds fewer items; repeat until it reports converged.-## `/speckit.taskstoissues`+## `/speckit.taskstoissues` (deprecated core command)-Optionally converts an existing `tasks.md` into actionable GitHub issues. Run it-after generating tasks when you want to track execution in GitHub:+The core command is deprecated and will be removed in a future minor release.+It warns when invoked, then continues its existing workflow without installing+or enabling the extension automatically.++The recommended extension command optionally converts an existing `tasks.md`+into actionable GitHub issues. Install the extension from your project root:++```bash+specify extension add github+```++Then invoke it in your agent after generating tasks when you want to track+execution in GitHub:```text-/speckit.taskstoissues+/speckit.github.taskstoissues```This command requires a GitHub `origin` remote and access to the GitHub MCP tools@@ -173,4 +184,4 @@ identified by that remote and checks existing task IDs to avoid duplicates.It is not required to implement tasks or converge on a feature.> [!NOTE]-> GitHub issue tracking is moving out of core into the bundled, opt-in [`github` extension](https://github.com/github/spec-kit/blob/main/extensions/github/README.md). `/speckit.taskstoissues` still works and is unchanged. Install its namespaced replacement with `specify extension add github`; the `generic` integration registers it under its configured command directory in commands or skills mode. See the [installation and migration notes](https://github.com/github/spec-kit/blob/main/extensions/github/README.md#installation).+> GitHub issue tracking uses the bundled, opt-in [`github` extension](https://github.com/github/spec-kit/blob/main/extensions/github/README.md). Its recommended command is `/speckit.github.taskstoissues` (slash-hyphen integrations: `/speckit-github-taskstoissues`; Codex, ZCode, and Command Code skills: `$speckit-github-taskstoissues`; Kimi: `/skill:speckit-github-taskstoissues`); the deprecated core `/speckit.taskstoissues` remains available during migration. The `generic` integration registers the extension under its configured command directory in commands or skills mode. See the [installation and migration notes](https://github.com/github/spec-kit/blob/main/extensions/github/README.md#installation) for all integration-specific invocation syntaxes.diff --git a/docs/reference/extensions.md b/docs/reference/extensions.mdindex cca791833..e39ff9d69 100644--- a/docs/reference/extensions.md+++ b/docs/reference/extensions.md@@ -30,7 +30,7 @@ specify extension add <name>| `--force` | Overwrite if the extension is already installed || `--priority <N>`| Resolution priority (default: 10; lower = higher precedence) |-Installs an extension from the catalog, a URL, or a local directory. Extension commands are registered with the active AI coding agent integration. For `generic`, invocations use the configured `--commands-dir`: flat command files by default, or `speckit-<name>/SKILL.md` with `--skills`. The core `speckit.taskstoissues` command remains available alongside the GitHub extension's namespaced replacement during migration.+Installs an extension from the catalog, a URL, or a local directory. Extension commands are registered with the active AI coding agent integration. For `generic`, invocations use the configured `--commands-dir`: flat command files by default, or `speckit-<name>/SKILL.md` with `--skills`. The deprecated core `speckit.taskstoissues` command remains available during migration and will be removed in a future minor release. It warns on invocation and continues its existing workflow without installing or enabling the extension automatically. For GitHub issue tracking, run `specify extension add github` and use the recommended `/speckit.github.taskstoissues` command (slash-hyphen integrations: `/speckit-github-taskstoissues`; Codex, ZCode, and Command Code skills: `$speckit-github-taskstoissues`; Kimi: `/skill:speckit-github-taskstoissues`).If a generic integration refresh cannot produce every extension invocation (for example, because a command or skill is user-modified or its source is missing), it warns and restores that extension's prior registered artifacts. Other extensions can still refresh.diff --git a/docs/reference/integrations.md b/docs/reference/integrations.mdindex 4bbbb4704..1e816d49f 100644--- a/docs/reference/integrations.md+++ b/docs/reference/integrations.md@@ -336,9 +336,14 @@ Once `generic` is the active integration, `specify extension add` registersextension commands in its configured `--commands-dir` (as command files orskills according to `--skills`). `specify extension remove` removes unchangedextension-owned artifacts while leaving core commands, user files, and edited-extension files intact. The core `speckit.taskstoissues` command remains-available; installing the GitHub extension adds the namespaced replacement-without deprecating or removing the core command.+extension files intact. The deprecated core `speckit.taskstoissues` command+remains available, warns on invocation, and will be removed in a future minor+release. To migrate, run `specify extension add github` and use the recommended+`/speckit.github.taskstoissues` command for dot-command integrations. Slash-hyphen+integrations use `/speckit-github-taskstoissues`; Codex, ZCode, and Command Code+skills use `$speckit-github-taskstoissues`; Kimi uses+`/skill:speckit-github-taskstoissues`. The core command continues its existing+workflow and does not install or enable the extension automatically.## Scaffold a New Integrationdiff --git a/extensions/catalog.json b/extensions/catalog.jsonindex 91c0140db..bc3b6cb02 100644--- a/extensions/catalog.json+++ b/extensions/catalog.json@@ -66,7 +66,7 @@"github": {"name": "GitHub Integration","id": "github",- "version": "1.0.1",+ "version": "1.0.2","description": "GitHub platform integration for Spec Kit - create GitHub issues from a feature's task list","author": "spec-kit-core","repository": "https://github.com/github/spec-kit",diff --git a/extensions/github/README.md b/extensions/github/README.mdindex ade406599..8aaf46a5c 100644--- a/extensions/github/README.md+++ b/extensions/github/README.md@@ -24,7 +24,8 @@ The `generic` (bring your own agent) integration registers this command underits configured `--commands-dir` in both commands and skills layouts. Installing`github` creates `speckit.github.taskstoissues.md` in commands mode or`speckit-github-taskstoissues/SKILL.md` in skills mode. The core-`speckit.taskstoissues` command remains available and unchanged. See+`speckit.taskstoissues` command is deprecated but remains available during migration.+Use this extension's recommended command instead. See[integration-specific options](../../docs/reference/integrations.md#integration-specific-options).## Removal@@ -37,9 +38,9 @@ specify extension remove github| Command | Description || ------------------------------ | -------------------------------------------------------------------- |-| `speckit.github.taskstoissues` | Convert tasks from `tasks.md` into dependency-ordered GitHub issues. |+| `speckit.github.taskstoissues` | Recommended: convert tasks from `tasks.md` into dependency-ordered GitHub issues. |-> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.github.taskstoissues` for dot-command integrations; `/speckit-github-taskstoissues` for hyphen/skills integrations (including Forge and Cline); `$speckit-github-taskstoissues` for Codex, ZCode, or Command Code in skills mode; or `/skill:speckit-github-taskstoissues` for Kimi.+> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.github.taskstoissues` for dot-command integrations; `/speckit-github-taskstoissues` for slash-hyphen integrations (including Forge and Cline); `$speckit-github-taskstoissues` for Codex, ZCode, or Command Code in skills mode; or `/skill:speckit-github-taskstoissues` for Kimi.### What the command does@@ -81,9 +82,21 @@ Prerequisite errors name the Spec Kit command without assuming an integration'sSpec Kit is moving GitHub issue tracking out of core in three stages:-1. **Now** β this extension is available, and the core `/speckit.taskstoissues` command remains available and unchanged. Nothing breaks if you do nothing.-2. **Next** β the core command is deprecated once the replacement has been available for a release.-3. **Later** β the core command is removed in a minor release.+1. **Initial stage (completed)** β this extension shipped with the core `/speckit.taskstoissues` command still available.+2. **Next (current stage)** β the replacement has been available for at least one release, so the core command is now deprecated. It displays a migration warning and continues its existing workflow. It does not install or enable the extension automatically or run the replacement command.+3. **Later** β the core command will be removed in a future minor release.++For existing projects, upgrading the CLI alone does not refresh the generated+core command files. After upgrading the CLI, run this from the project root:++```bash+specify integration upgrade <key>+```++Replace `<key>` with the installed integration key, or omit it to upgrade the+default integration. This refreshes the core command with the deprecation+warning. If locally modified files block the upgrade, inspect those changes+before deciding whether to overwrite them. See [Upgrade an Integration](../../docs/reference/integrations.md#upgrade-an-integration).To migrate, install the extension and use the namespaced command instead:@@ -93,10 +106,42 @@ specify extension add githubThe `generic` integration supports this migration in both commands and skillslayouts under its configured `--commands-dir`. The core command remains-available until a separate deprecation and removal decision.+available during this deprecation period until the removal stage.-| Before | After |+| Deprecated core command | Recommended extension command || ------------------------- | --------------------------------- || `/speckit.taskstoissues` | `/speckit.github.taskstoissues` |-Behavior is unchanged: the same feature resolution, the same `plan.md` and `tasks.md` prerequisites, the same remote validation, the same deduplication across open and closed issues, the same issue titles, and the same hook contract. This extension does **not** register `speckit.taskstoissues` as an alias, so the two commands coexist without shadowing each other while the core command still exists.+Apart from the core command's deprecation warning, conversion behavior is unchanged: the same feature resolution, the same `plan.md` and `tasks.md` prerequisites, the same remote validation, the same deduplication across open and closed issues, the same issue titles, and the same hook contract. This extension does **not** register `speckit.taskstoissues` as an alias, so the two commands coexist without shadowing each other while the core command still exists.++### Presets and dependent extensions++Before the core command is removed, audit references to `speckit.taskstoissues`+in presets, extension prompts, workflow steps, handoffs, and project automation.+For GitHub issue conversion, use the canonical `speckit.github.taskstoissues`+command ID and render it with the agent-specific syntax under [Commands](#commands).+Replace `__SPECKIT_COMMAND_TASKSTOISSUES__` cross-command references with+`__SPECKIT_COMMAND_GITHUB_TASKSTOISSUES__` where template rendering is supported.+Document `specify extension add github` as a setup prerequisite; the deprecation+warning does not install this dependency.++If an extension proposal or external dependency declaration uses+`requires.commands: [speckit.taskstoissues]`, update its target to+`speckit.github.taskstoissues`. `requires.commands` is not an enforced dependency+field in the current extension manifest API, so do not rely on that declaration+to install or check the GitHub extension. Follow the supported requirements in+the [extension API reference](../EXTENSION-API-REFERENCE.md#extension-manifest).++Preset command overrides are separate from command references: an override of+`speckit.taskstoissues` does not automatically customize the namespaced GitHub+command. Review and port any needed customization, then verify the installed+command in a sample project before retiring the old override. A preset that+uses another issue tracker should retain its own provider-specific workflow+rather than redirecting it to the GitHub command. Existing overrides may also+hide the core deprecation warning, so communicate the migration to their users.++Keep the `before_taskstoissues` and `after_taskstoissues` hook keys unchanged;+both commands consume them. Only update a hook's command reference if it invokes+the deprecated command. Do not invoke both core and replacement commands for+the same conversion, since that also runs their hooks twice. Publish and test+updated preset/extension versions before the later core-removal release.diff --git a/extensions/github/extension.yml b/extensions/github/extension.ymlindex 2e13c434b..c6df8f19a 100644--- a/extensions/github/extension.yml+++ b/extensions/github/extension.yml@@ -3,7 +3,7 @@ schema_version: "1.0"extension:id: githubname: "GitHub Integration"- version: "1.0.1"+ version: "1.0.2"description: "GitHub platform integration for Spec Kit - create GitHub issues from a feature's task list"author: spec-kit-corerepository: https://github.com/github/spec-kitdiff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex 68ea5e498..de09603b4 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -380,7 +380,7 @@ SKILL_DESCRIPTIONS = {"clarify": "Structured clarification workflow for underspecified requirements.","constitution": "Create or update project governing principles and development guidelines.","checklist": "Generate custom quality checklists for validating requirements completeness and clarity.",- "taskstoissues": "Convert tasks from tasks.md into GitHub issues.",+ "taskstoissues": "Deprecated: Convert tasks from tasks.md into GitHub issues.",}diff --git a/templates/commands/taskstoissues.md b/templates/commands/taskstoissues.mdindex f98244890..dea7e7cfe 100644--- a/templates/commands/taskstoissues.md+++ b/templates/commands/taskstoissues.md@@ -1,5 +1,5 @@----description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.+description: "Deprecated: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts."tools: ['github/github-mcp-server/list_issues', 'github/github-mcp-server/issue_write']scripts:sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks@@ -7,6 +7,14 @@ scripts:py: scripts/python/check_prerequisites.py --json --require-tasks --include-tasks---+## Deprecation Notice++You **MUST display the following concise warning first**, as the first step of this command and before the User Input and Pre-Execution Checks sections below:++> β οΈ `__SPECKIT_COMMAND_TASKSTOISSUES__` is deprecated and will be removed in a future minor release. Use the bundled `github` extension instead: run `specify extension add github`, then invoke `__SPECKIT_COMMAND_GITHUB_TASKSTOISSUES__`.++Continue with the existing workflow unchanged. Do not install or enable the extension automatically, do not stop, and do not run the replacement command.+## User Input```textdiff --git a/tests/extensions/github/test_github_extension.py b/tests/extensions/github/test_github_extension.pyindex 498abaf36..718c1c842 100644--- a/tests/extensions/github/test_github_extension.py+++ b/tests/extensions/github/test_github_extension.py@@ -158,7 +158,7 @@ class TestManifest:m = ExtensionManifest(EXT_DIR / "extension.yml")assert m.id == "github"- assert m.version == "1.0.1"+ assert m.version == "1.0.2"assert [c["name"] for c in m.commands] == [COMMAND_NAME]def test_manifest_command_files_exist(self):@@ -598,17 +598,24 @@ class TestCommandBody:# Four-digit and longer task IDs must still match.assert r"\bT\d{3,}\b" in body- def test_body_differs_from_core_only_in_the_script_invocation(self):+ def test_body_differs_from_core_only_in_deprecation_and_script_invocation(self):"""Behaviour parity, enforced as a diff rather than as spot checks.- Everything except the ``scripts:`` frontmatter and the two lines that- read the new ``TASKS`` value must match the core command verbatim, so- the two cannot silently drift while both exist.+ Apart from core-only deprecation metadata and notice, everything except+ the ``scripts:`` frontmatter and the two lines that read the new ``TASKS``+ value must match verbatim, so the two cannot silently drift while both exist."""import difflib- core = CORE_COMMAND.read_text(encoding="utf-8").splitlines()+ core_text = CORE_COMMAND.read_text(encoding="utf-8")+ before_notice, notice_and_workflow = core_text.split("## Deprecation Notice\n", 1)+ _, workflow = notice_and_workflow.split("## User Input", 1)+ core = (before_notice + "## User Input" + workflow).splitlines()ext = COMMAND_FILE.read_text(encoding="utf-8").splitlines()+ core_description = yaml.safe_load(core[1])["description"]+ ext_description = yaml.safe_load(ext[1])["description"]+ assert core_description == "Deprecated: " + ext_description+ core[1] = ext[1]changed = [linefor line in difflib.unified_diff(core, ext, n=0)diff --git a/tests/extensions/github/test_taskstoissues_deprecation.py b/tests/extensions/github/test_taskstoissues_deprecation.pynew file mode 100644index 000000000..b18324863--- /dev/null+++ b/tests/extensions/github/test_taskstoissues_deprecation.py@@ -0,0 +1,99 @@+"""Text contracts for the core command's deprecation transition."""++from pathlib import Path++import pytest+import yaml+++ROOT = Path(__file__).resolve().parents[3]+CORE = ROOT / "templates/commands/taskstoissues.md"+EXTENSION = ROOT / "extensions/github/commands/speckit.github.taskstoissues.md"+++def test_core_deprecation_warning_and_continuation():+ text = CORE.read_text(encoding="utf-8")+ assert "## Deprecation Notice" in text+ assert "## Pre-Execution Checks" in text+ notice = text.split("## Deprecation Notice\n", 1)[1].split("## User Input", 1)[0]+ assert text.index("## Deprecation Notice") < text.index("## User Input") < text.index("## Pre-Execution Checks")+ for phrase in (+ "MUST display the following concise warning first",+ "`__SPECKIT_COMMAND_TASKSTOISSUES__` is deprecated",+ "will be removed in a future minor release",+ "bundled `github` extension",+ "specify extension add github",+ "__SPECKIT_COMMAND_GITHUB_TASKSTOISSUES__",+ "Continue with the existing workflow unchanged",+ "Do not install or enable the extension automatically",+ "do not stop",+ "do not run the replacement command",+ ):+ assert phrase in notice+++def test_core_frontmatter_preserves_execution_metadata():+ metadata = yaml.safe_load(CORE.read_text(encoding="utf-8").split("---", 2)[1])+ assert metadata["description"].startswith("Deprecated: ")+ assert metadata["tools"] == [+ "github/github-mcp-server/list_issues",+ "github/github-mcp-server/issue_write",+ ]+ assert metadata["scripts"] == {+ "sh": "scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks",+ "ps": "scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks",+ "py": "scripts/python/check_prerequisites.py --json --require-tasks --include-tasks",+ }+++def test_recommended_extension_is_not_deprecated():+ text = EXTENSION.read_text(encoding="utf-8")+ assert "## Deprecation Notice" not in text+ assert "future minor release" not in text+ assert not yaml.safe_load(text.split("---", 2)[1])["description"].startswith("Deprecated:")++[email protected]("command", [CORE, EXTENSION], ids=["core", "github"])+def test_taskstoissues_hooks_and_safety_contracts_remain(command):+ text = command.read_text(encoding="utf-8")+ assert "hooks.before_taskstoissues" in text+ assert "hooks.after_taskstoissues" in text+ assert "ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL" in text+ assert "**Fetch existing issues for deduplication**" in text+ assert "**Skip** any task whose ID is already present" in text+ assert "Only create issues for tasks that do not yet have a matching issue." in text+ assert "UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL" in text+++ ("integration_key", "core_invocation", "replacement_invocation"),+ [+ ("opencode", "/speckit.taskstoissues", "/speckit.github.taskstoissues"),+ ("agy", "/speckit-taskstoissues", "/speckit-github-taskstoissues"),+ ],+)+def test_rendered_core_warning_uses_integration_invocations(+ tmp_path, integration_key, core_invocation, replacement_invocation+):+ from specify_cli.integrations import get_integration+ from specify_cli.integrations.manifest import IntegrationManifest++ integration = get_integration(integration_key)+ created = integration.setup(+ tmp_path, IntegrationManifest(integration_key, tmp_path), script_type="sh"+ )+ command = next(+ path for path in created+ if path.name == "speckit.taskstoissues.md"+ or path.parent.name == "speckit-taskstoissues"+ )+ text = command.read_text(encoding="utf-8")+ assert "## Deprecation Notice" in text+ assert "## Pre-Execution Checks" in text+ notice = text.split("## Deprecation Notice", 1)[1].split("## User Input", 1)[0]+ assert f"`{core_invocation}` is deprecated" in notice+ assert f"invoke `{replacement_invocation}`" in notice+ assert "__SPECKIT_COMMAND_" not in notice+ assert "specify extension add github" in notice+ assert "Continue with the existing workflow unchanged" in notice+ assert "Do not install or enable the extension automatically" in notice