Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

feat: add native Cline integration (#2508)

Pedro Barbosa44aac9f6e44f
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
index ec6c89465..ebb34eb9d 100644
--- a/docs/reference/integrations.md
+++ b/docs/reference/integrations.md
@@ -10,6 +10,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
| [Antigravity (agy)](https://antigravity.google/) | `agy` | Skills-based integration; skills are installed automatically |
| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | `auggie` | |
| [Claude Code](https://www.anthropic.com/claude-code) | `claude` | Skills-based integration; installs skills in `.claude/skills` |
+| [Cline](https://github.com/cline/cline) | `cline` | IDE-based agent |
| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | `codebuddy` | |
| [Codex CLI](https://github.com/openai/codex) | `codex` | Skills-based integration; installs skills into `.agents/skills` and invokes them as `$speckit-<command>` |
| [Cursor](https://cursor.sh/) | `cursor-agent` | |
diff --git a/integrations/catalog.json b/integrations/catalog.json
index e10f594c6..adf31be78 100644
--- a/integrations/catalog.json
+++ b/integrations/catalog.json
@@ -1,6 +1,6 @@
{
"schema_version": "1.0",
- "updated_at": "2026-04-29T00:00:00Z",
+ "updated_at": "2026-05-13T00:00:00Z",
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/integrations/catalog.json",
"integrations": {
"claude": {
@@ -12,6 +12,15 @@
"repository": "https://github.com/github/spec-kit",
"tags": ["cli", "anthropic"]
},
+ "cline": {
+ "id": "cline",
+ "name": "Cline",
+ "version": "1.0.0",
+ "description": "Cline IDE integration",
+ "author": "spec-kit-core",
+ "repository": "https://github.com/github/spec-kit",
+ "tags": ["ide"]
+ },
"copilot": {
"id": "copilot",
"name": "GitHub Copilot",
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py
index 08b0b7846..4bd23622d 100644
--- a/src/specify_cli/__init__.py
+++ b/src/specify_cli/__init__.py
@@ -3241,9 +3241,17 @@ def extension_add(
for warning in manifest.warnings:
console.print(f"\n[yellow]⚠ Compatibility warning:[/yellow] {warning}")
+ is_cline = load_init_options(project_root).get("ai") == "cline"
+
+ if is_cline:
+ from specify_cli.integrations.cline import format_cline_command_name
+
console.print("\n[bold cyan]Provided commands:[/bold cyan]")
for cmd in manifest.commands:
- console.print(f" β€’ {cmd['name']} - {cmd.get('description', '')}")
+ cmd_name = cmd['name']
+ if is_cline:
+ cmd_name = format_cline_command_name(cmd_name)
+ console.print(f" β€’ {cmd_name} - {cmd.get('description', '')}")
# Report agent skills registration
reg_meta = manager.registry.get(manifest.id)
diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.py
index 404a3a0a0..d7af7191d 100644
--- a/src/specify_cli/agents.py
+++ b/src/specify_cli/agents.py
@@ -67,6 +67,33 @@ class CommandRegistrar:
except ImportError:
pass # Circular import during module init; retry on next access
+ @staticmethod
+ def _hyphenate_frontmatter_refs(val: Any) -> Any:
+ """Recursively find any dotted references starting with speckit. and hyphenate them."""
+ if isinstance(val, dict):
+ return {
+ k: CommandRegistrar._hyphenate_frontmatter_refs(v)
+ for k, v in val.items()
+ }
+ elif isinstance(val, list):
+ return [CommandRegistrar._hyphenate_frontmatter_refs(x) for x in val]
+ elif isinstance(val, str):
+ return re.sub(
+ r"\bspeckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*\b",
+ lambda m: m.group(0).replace(".", "-"),
+ val,
+ )
+ return val
+
+ @staticmethod
+ def _hyphenate_body_refs(body: str) -> str:
+ """Hyphenate dotted speckit references in command body text."""
+ return re.sub(
+ r"\bspeckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*\b",
+ lambda m: m.group(0).replace(".", "-"),
+ body,
+ )
+
@staticmethod
def parse_frontmatter(content: str) -> tuple[dict, str]:
"""Parse YAML frontmatter from Markdown content.
@@ -408,6 +435,9 @@ class CommandRegistrar:
) -> str:
"""Compute the on-disk command or skill name for an agent."""
if agent_config["extension"] != "/SKILL.md":
+ format_name = agent_config.get("format_name")
+ if format_name:
+ return format_name(cmd_name)
return cmd_name
short_name = cmd_name
@@ -437,6 +467,13 @@ class CommandRegistrar:
if not normalized.is_relative_to(base_normalized):
raise ValueError(f"Output path {candidate!r} escapes directory {base!r}")
+ @staticmethod
+ def _is_safe_command_name(name: str) -> bool:
+ """Reject names that could escape the commands directory via path traversal."""
+ if os.path.sep in name or "/" in name or "\\" in name:
+ return False
+ return os.path.normpath(name) == name
+
def register_commands(
self,
agent_name: str,
@@ -482,9 +519,11 @@ class CommandRegistrar:
commands_dir.mkdir(parents=True, exist_ok=True)
registered = []
+ is_cline_ext = agent_name == "cline" and source_id != "core"
for cmd_info in commands:
cmd_name = cmd_info["name"]
+ aliases = cmd_info.get("aliases", [])
cmd_file = cmd_info["file"]
source_file = source_dir / cmd_file
@@ -516,6 +555,10 @@ class CommandRegistrar:
format_name = agent_config.get("format_name")
frontmatter["name"] = format_name(cmd_name) if format_name else cmd_name
+ if is_cline_ext:
+ frontmatter = self._hyphenate_frontmatter_refs(frontmatter)
+ body = self._hyphenate_body_refs(body)
+
body = self._convert_argument_placeholder(
body, "$ARGUMENTS", agent_config["args"]
)
@@ -585,7 +628,7 @@ class CommandRegistrar:
registered.append(cmd_name)
- for alias in cmd_info.get("aliases", []):
+ for alias in aliases:
alias_output_name = self._compute_output_name(
agent_name, alias, agent_config
)
@@ -909,22 +952,32 @@ class CommandRegistrar:
output_name = self._compute_output_name(
agent_name, cmd_name, agent_config
)
+
+ names_to_clean = [output_name]
+ if output_name != cmd_name and self._is_safe_command_name(cmd_name):
+ names_to_clean.append(cmd_name)
+
for target_dir in dirs_to_clean:
- cmd_file = (
- target_dir / f"{output_name}{agent_config['extension']}"
- )
- if cmd_file.exists() or cmd_file.is_symlink():
- cmd_file.unlink()
- # For SKILL.md agents each command lives in its own
- # subdirectory (e.g. .agents/skills/speckit-ext-cmd/
- # SKILL.md). Remove the parent dir when it becomes
- # empty to avoid orphaned directories.
- parent = cmd_file.parent
- if parent != target_dir and parent.exists():
- try:
- parent.rmdir()
- except OSError:
- pass
+ for name in names_to_clean:
+ cmd_file = (
+ target_dir / f"{name}{agent_config['extension']}"
+ )
+ try:
+ self._ensure_inside(cmd_file, target_dir)
+ except ValueError:
+ continue
+ if cmd_file.exists() or cmd_file.is_symlink():
+ cmd_file.unlink()
+ # For SKILL.md agents each command lives in its own
+ # subdirectory (e.g. .agents/skills/speckit-ext-cmd/
+ # SKILL.md). Remove the parent dir when it becomes
+ # empty to avoid orphaned directories.
+ parent = cmd_file.parent
+ if parent != target_dir and parent.exists():
+ try:
+ parent.rmdir()
+ except OSError:
+ pass
if agent_name == "copilot":
prompt_file = (
diff --git a/src/specify_cli/commands/init.py b/src/specify_cli/commands/init.py
index e5dc47e98..da4a15f51 100644
--- a/src/specify_cli/commands/init.py
+++ b/src/specify_cli/commands/init.py
@@ -726,6 +726,7 @@ def register(app: typer.Typer) -> None:
cursor_agent_skill_mode = selected_ai == "cursor-agent" and (ai_skills or _is_skills_integration)
copilot_skill_mode = selected_ai == "copilot" and _is_skills_integration
devin_skill_mode = selected_ai == "devin"
+ cline_skill_mode = selected_ai == "cline"
native_skill_mode = codex_skill_mode or claude_skill_mode or kimi_skill_mode or agy_skill_mode or trae_skill_mode or cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode
if codex_skill_mode and not ai_skills:
@@ -749,7 +750,7 @@ def register(app: typer.Typer) -> None:
return f"/speckit-{name}"
if kimi_skill_mode:
return f"/skill:speckit-{name}"
- if cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode:
+ if cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode or cline_skill_mode:
return f"/speckit-{name}"
return f"/speckit.{name}"
diff --git a/src/specify_cli/extensions.py b/src/specify_cli/extensions.py
index 5a595fbff..d36f3d5a5 100644
--- a/src/specify_cli/extensions.py
+++ b/src/specify_cli/extensions.py
@@ -2413,6 +2413,7 @@ class HookExecutor:
claude_skill_mode = selected_ai == "claude" and bool(init_options.get("ai_skills"))
kimi_skill_mode = selected_ai == "kimi"
cursor_skill_mode = selected_ai == "cursor-agent" and bool(init_options.get("ai_skills"))
+ cline_mode = selected_ai == "cline"
skill_name = self._skill_name_from_command(command_id)
if codex_skill_mode and skill_name:
@@ -2423,6 +2424,10 @@ class HookExecutor:
return f"/skill:{skill_name}"
if cursor_skill_mode and skill_name:
return f"/{skill_name}"
+ if cline_mode:
+ from .integrations.cline import format_cline_command_name
+
+ return f"/{format_cline_command_name(command_id)}"
return f"/{command_id}"
diff --git a/src/specify_cli/integrations/__init__.py b/src/specify_cli/integrations/__init__.py
index ad1440d07..37ef1a333 100644
--- a/src/specify_cli/integrations/__init__.py
+++ b/src/specify_cli/integrations/__init__.py
@@ -52,6 +52,7 @@ def _register_builtins() -> None:
from .auggie import AuggieIntegration
from .bob import BobIntegration
from .claude import ClaudeIntegration
+ from .cline import ClineIntegration
from .codebuddy import CodebuddyIntegration
from .codex import CodexIntegration
from .copilot import CopilotIntegration
@@ -85,6 +86,7 @@ def _register_builtins() -> None:
_register(AuggieIntegration())
_register(BobIntegration())
_register(ClaudeIntegration())
+ _register(ClineIntegration())
_register(CodebuddyIntegration())
_register(CodexIntegration())
_register(CopilotIntegration())
diff --git a/src/specify_cli/integrations/cline/__init__.py b/src/specify_cli/integrations/cline/__init__.py
new file mode 100644
index 000000000..c269a1604
--- /dev/null
+++ b/src/specify_cli/integrations/cline/__init__.py
@@ -0,0 +1,162 @@
+"""Cline IDE integration."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from ..base import MarkdownIntegration
+from ..manifest import IntegrationManifest
+
+
+# Note injected into hook sections so Cline maps dot-notation command
+# names (from extensions.yml) to the hyphenated slash commands it uses.
+_HOOK_COMMAND_NOTE = (
+ "- When constructing slash commands from hook command names, "
+ "replace dots (`.`) with hyphens (`-`). "
+ "For example, `speckit.git.commit` β†’ `/speckit-git-commit`.\n"
+)
+
+
+def format_cline_command_name(cmd_name: str) -> str:
+ """Convert command name to Cline-compatible hyphenated format.
+
+ Cline handles slash-commands optimally when they use hyphens instead of dots.
+ This function converts dot-notation command names to hyphenated format.
+
+ The function is idempotent: already-formatted names are returned unchanged.
+
+ Examples:
+ >>> format_cline_command_name("plan")
+ 'speckit-plan'
+ >>> format_cline_command_name("speckit.plan")
+ 'speckit-plan'
+ >>> format_cline_command_name("speckit.git.commit")
+ 'speckit-git-commit'
+
+ Args:
+ cmd_name: Command name in dot notation (speckit.foo.bar),
+ hyphenated format (speckit-foo-bar), or plain name (foo)
+
+ Returns:
+ Hyphenated command name with 'speckit-' prefix
+ """
+ cmd_name = cmd_name.replace(".", "-")
+
+ if not cmd_name.startswith("speckit-"):
+ cmd_name = f"speckit-{cmd_name}"
+
+ return cmd_name
+
+
+class ClineIntegration(MarkdownIntegration):
+ """Integration for Cline IDE."""
+
+ key = "cline"
+ config = {
+ "name": "Cline",
+ "folder": ".clinerules/",
+ "commands_subdir": "workflows",
+ "install_url": "https://github.com/cline/cline",
+ "requires_cli": False,
+ }
+ registrar_config = {
+ "dir": ".clinerules/workflows",
+ "format": "markdown",
+ "args": "$ARGUMENTS",
+ "extension": ".md",
+ "inject_name": True,
+ "format_name": format_cline_command_name,
+ "invoke_separator": "-",
+ }
+ context_file = ".clinerules/specify-rules.md"
+ invoke_separator = "-"
+ multi_install_safe = True
+
+ def command_filename(self, template_name: str) -> str:
+ """Cline uses hyphenated filenames (e.g. speckit-git-commit.md)."""
+ return format_cline_command_name(template_name) + ".md"
+
+ def process_template(self, *args, **kwargs):
+ """Ensure shared templates render Cline command references with hyphens."""
+ kwargs.setdefault("invoke_separator", self.invoke_separator)
+ return super().process_template(*args, **kwargs)
+
+ @staticmethod
+ def _inject_hook_command_note(content: str) -> str:
+ """Insert a dot-to-hyphen note before each hook output instruction.
+
+ Targets the line ``- For each executable hook, output the following``
+ and inserts the note on the line before it, matching its indentation.
+ Skips if the note is already present.
+ """
+ if "replace dots" in content:
+ return content
+
+ def repl(m: re.Match[str]) -> str:
+ indent = m.group(1)
+ instruction = m.group(2)
+ eol = m.group(3)
+ return (
+ indent
+ + _HOOK_COMMAND_NOTE.rstrip("\n")
+ + eol
+ + indent
+ + instruction
+ + eol
+ )
+
+ return re.sub(
+ r"(?m)^(\s*)(- For each executable hook, output the following[^\r\n]*)(\r\n|\n|$)",
+ repl,
+ content,
+ )
+
+ @staticmethod
+ def _rewrite_handoff_references(content: str) -> str:
+ """Replace dot-notation agent references in handoffs with hyphens."""
+ return re.sub(
+ r"(?m)^(\s*agent:\s*)(speckit\.[A-Za-z0-9-_]+(?:\.[A-Za-z0-9-_]+)*)",
+ lambda m: f"{m.group(1)}{format_cline_command_name(m.group(2))}",
+ content,
+ )
+
+ def post_process_content(self, content: str) -> str:
+ """Apply Cline-specific transformations to command content."""
+ updated = self._inject_hook_command_note(content)
+ updated = self._rewrite_handoff_references(updated)
+ return updated
+
+ def setup(
+ self,
+ project_root: Path,
+ manifest: IntegrationManifest,
+ parsed_options: dict[str, Any] | None = None,
+ **opts: Any,
+ ) -> list[Path]:
+ """Install Cline commands and apply post-processing transformations."""
+ created = super().setup(project_root, manifest, parsed_options, **opts)
+
+ # Post-process generated command files
+ dest_dir = self.commands_dest(project_root).resolve()
+
+ for path in created:
+ # Only touch .md files under the commands directory
+ try:
+ path.resolve().relative_to(dest_dir)
+ except ValueError:
+ continue
+ if path.suffix != ".md":
+ continue
+
+ content_bytes = path.read_bytes()
+ content = content_bytes.decode("utf-8")
+
+ updated = self.post_process_content(content)
+
+ if updated != content:
+ path.write_bytes(updated.encode("utf-8"))
+ self.record_file_in_manifest(path, project_root, manifest)
+
+ return created
diff --git a/tests/integrations/test_cli.py b/tests/integrations/test_cli.py
index 0c793cd7f..6198f294a 100644
--- a/tests/integrations/test_cli.py
+++ b/tests/integrations/test_cli.py
@@ -330,6 +330,7 @@ class TestInitIntegrationFlag:
def test_shared_infra_skip_warning_displayed(self, tmp_path, capsys):
"""Console warning is displayed when files are skipped."""
from specify_cli import _install_shared_infra
+ from tests.conftest import strip_ansi
project = tmp_path / "warn-test"
project.mkdir()
diff --git a/tests/integrations/test_integration_cline.py b/tests/integrations/test_integration_cline.py
new file mode 100644
index 000000000..fbfc319f5
--- /dev/null
+++ b/tests/integrations/test_integration_cline.py
@@ -0,0 +1,213 @@
+"""Tests for ClineIntegration."""
+
+import os
+import pytest
+
+from specify_cli.integrations import get_integration
+from specify_cli.integrations.cline import format_cline_command_name
+from .test_integration_base_markdown import MarkdownIntegrationTests
+
+
+class TestClineCommandNameFormatter:
+ """Test the Cline command name formatter."""
+
+ def test_simple_name_without_prefix(self):
+ """Test formatting a simple name without 'speckit.' prefix."""
+ assert format_cline_command_name("plan") == "speckit-plan"
+ assert format_cline_command_name("tasks") == "speckit-tasks"
+ assert format_cline_command_name("specify") == "speckit-specify"
+
+ def test_name_with_speckit_prefix(self):
+ """Test formatting a name that already has 'speckit.' prefix."""
+ assert format_cline_command_name("speckit.plan") == "speckit-plan"
+ assert format_cline_command_name("speckit.tasks") == "speckit-tasks"
+
+ def test_extension_command_name(self):
+ """Test formatting extension command names with dots."""
+ assert (
+ format_cline_command_name("speckit.my-extension.example")
+ == "speckit-my-extension-example"
+ )
+ assert (
+ format_cline_command_name("my-extension.example")
+ == "speckit-my-extension-example"
+ )
+
+ def test_idempotent_already_hyphenated(self):
+ """Test that already-hyphenated names are returned unchanged (idempotent)."""
+ assert format_cline_command_name("speckit-plan") == "speckit-plan"
+ assert (
+ format_cline_command_name("speckit-my-extension-example")
+ == "speckit-my-extension-example"
+ )
+
+
+class TestClineIntegration(MarkdownIntegrationTests):
+ KEY = "cline"
+ FOLDER = ".clinerules/"
+ COMMANDS_SUBDIR = "workflows"
+ REGISTRAR_DIR = ".clinerules/workflows"
+ CONTEXT_FILE = ".clinerules/specify-rules.md"
+
+ @pytest.mark.parametrize(
+ "cmd_name, expected_filename",
+ [
+ ("plan", "speckit-plan.md"),
+ ("speckit.plan", "speckit-plan.md"),
+ ("speckit.git.commit", "speckit-git-commit.md"),
+ ("speckit", "speckit-speckit.md"),
+ ("speckitfoo", "speckit-speckitfoo.md"),
+ ],
+ )
+ def test_cline_command_filename(self, cmd_name, expected_filename):
+ """Verify Cline uses hyphenated filenames."""
+ cline = get_integration("cline")
+ assert cline.command_filename(cmd_name) == expected_filename
+
+ def test_cline_invoke_separator(self):
+ """Verify Cline uses hyphen as invoke separator."""
+ cline = get_integration("cline")
+ assert cline.invoke_separator == "-"
+ assert cline.registrar_config["invoke_separator"] == "-"
+
+ def test_cline_name_injection_and_formatting(self):
+ """Verify Cline has inject_name and format_name configured."""
+ cline = get_integration("cline")
+ assert cline.registrar_config["inject_name"] is True
+ assert cline.registrar_config["format_name"] == format_cline_command_name
+
+ def test_cline_handoff_rewrite(self):
+ """Verify Cline rewrites agent: speckit.foo to agent: speckit-foo."""
+ cline = get_integration("cline")
+ content = "---\nagent: speckit.plan\n---\n"
+ rewritten = cline._rewrite_handoff_references(content)
+ assert rewritten == "---\nagent: speckit-plan\n---\n"
+
+ def test_cline_hook_instruction_injection(self):
+ """Verify Cline injects the dot-to-hyphen note for hooks."""
+ cline = get_integration("cline")
+ content = "- For each executable hook, output the following:\n"
+ injected = cline._inject_hook_command_note(content)
+ assert "replace dots (`.`) with hyphens (`-`)" in injected
+ assert "- For each executable hook, output the following:" in injected
+
+ # -- Overrides for MarkdownIntegrationTests ---------------------------
+
+ def test_setup_creates_files(self, tmp_path):
+ from specify_cli.integrations.manifest import IntegrationManifest
+
+ i = get_integration(self.KEY)
+ m = IntegrationManifest(self.KEY, tmp_path)
+ created = i.setup(tmp_path, m)
+ assert len(created) > 0
+ cmd_files = [
+ f
+ for f in created
+ if "scripts" not in f.parts
+ and f.suffix == ".md"
+ and f.name != i.context_file
+ ]
+ for f in cmd_files:
+ assert f.exists()
+ assert f.name.startswith("speckit-")
+ assert f.name.endswith(".md")
+
+ specify_file = next(
+ (f for f in cmd_files if f.name == "speckit-specify.md"), None
+ )
+ assert specify_file is not None
+ specify_contents = specify_file.read_text(encoding="utf-8")
+ assert "/speckit-plan" in specify_contents
+ assert "/speckit.plan" not in specify_contents
+
+ def test_integration_flag_creates_files(self, tmp_path):
+ from typer.testing import CliRunner
+ from specify_cli import app
+
+ project = tmp_path / f"int-{self.KEY}"
+ project.mkdir()
+ old_cwd = os.getcwd()
+ try:
+ os.chdir(project)
+ runner = CliRunner()
+ result = runner.invoke(
+ app,
+ [
+ "init",
+ "--here",
+ "--integration",
+ self.KEY,
+ "--script",
+ "sh",
+ "--no-git",
+ "--ignore-agent-tools",
+ ],
+ catch_exceptions=False,
+ )
+ finally:
+ os.chdir(old_cwd)
+ assert result.exit_code == 0
+ i = get_integration(self.KEY)
+ cmd_dir = i.commands_dest(project)
+ assert cmd_dir.is_dir()
+ commands = sorted(cmd_dir.glob("speckit-*"))
+ assert len(commands) > 0
+
+ def _expected_files(self, script_variant: str) -> list[str]:
+ """Override to expect hyphenated speckit- prefix."""
+ i = get_integration(self.KEY)
+ cmd_dir = i.registrar_config["dir"]
+ files = []
+
+ # Command files
+ for stem in (
+ self.COMMANDS_SUBDIR_STEMS
+ if hasattr(self, "COMMANDS_SUBDIR_STEMS")
+ else self.COMMAND_STEMS
+ ):
+ files.append(f"{cmd_dir}/speckit-{stem.replace('.', '-')}.md")
+
+ # Framework files
+ files.append(".specify/integration.json")
+ files.append(".specify/init-options.json")
+ files.append(f".specify/integrations/{self.KEY}.manifest.json")
+ files.append(".specify/integrations/speckit.manifest.json")
+
+ if script_variant == "sh":
+ for name in [
+ "check-prerequisites.sh",
+ "common.sh",
+ "create-new-feature.sh",
+ "setup-plan.sh",
+ "setup-tasks.sh",
+ ]:
+ files.append(f".specify/scripts/bash/{name}")
+ else:
+ for name in [
+ "check-prerequisites.ps1",
+ "common.ps1",
+ "create-new-feature.ps1",
+ "setup-plan.ps1",
+ "setup-tasks.ps1",
+ ]:
+ files.append(f".specify/scripts/powershell/{name}")
+
+ for name in [
+ "checklist-template.md",
+ "constitution-template.md",
+ "plan-template.md",
+ "spec-template.md",
+ "tasks-template.md",
+ ]:
+ files.append(f".specify/templates/{name}")
+
+ files.append(".specify/memory/constitution.md")
+ # Bundled workflow
+ files.append(".specify/workflows/speckit/workflow.yml")
+ files.append(".specify/workflows/workflow-registry.json")
+
+ # Agent context file (if set)
+ if i.context_file:
+ files.append(i.context_file)
+
+ return sorted(files)
diff --git a/tests/integrations/test_integration_forge.py b/tests/integrations/test_integration_forge.py
index 62fee7321..f63afb71e 100644
--- a/tests/integrations/test_integration_forge.py
+++ b/tests/integrations/test_integration_forge.py
@@ -330,7 +330,7 @@ class TestForgeCommandRegistrar:
assert "speckit.my-extension.example" in registered
# Check the generated file has hyphenated name in frontmatter
- forge_cmd = tmp_path / ".forge" / "commands" / "speckit.my-extension.example.md"
+ forge_cmd = tmp_path / ".forge" / "commands" / "speckit-my-extension-example.md"
assert forge_cmd.exists()
content = forge_cmd.read_text(encoding="utf-8")
@@ -378,7 +378,7 @@ class TestForgeCommandRegistrar:
)
# Check the alias file has hyphenated name in frontmatter
- alias_file = tmp_path / ".forge" / "commands" / "speckit.my-extension.ex.md"
+ alias_file = tmp_path / ".forge" / "commands" / "speckit-my-extension-ex.md"
assert alias_file.exists()
content = alias_file.read_text(encoding="utf-8")
@@ -467,7 +467,7 @@ class TestForgeCommandRegistrar:
assert "speckit.git.feature" in registered
- forge_cmd = tmp_path / ".forge" / "commands" / "speckit.git.feature.md"
+ forge_cmd = tmp_path / ".forge" / "commands" / "speckit-git-feature.md"
assert forge_cmd.exists(), "Expected Forge command file was not created"
content = forge_cmd.read_text(encoding="utf-8")
diff --git a/tests/integrations/test_integration_subcommand.py b/tests/integrations/test_integration_subcommand.py
index f40adb7ae..e96640d78 100644
--- a/tests/integrations/test_integration_subcommand.py
+++ b/tests/integrations/test_integration_subcommand.py
@@ -185,7 +185,8 @@ class TestIntegrationInstall:
finally:
os.chdir(old_cwd)
assert result.exit_code == 0
- normalized = " ".join(result.output.split())
+ output = strip_ansi(result.output)
+ normalized = " ".join(output.split())
assert "already installed" in normalized
assert "specify integration use codex" in normalized
assert "specify integration upgrade codex" in normalized
diff --git a/tests/test_extensions.py b/tests/test_extensions.py
index 76eb9d498..cb6c3081a 100644
--- a/tests/test_extensions.py
+++ b/tests/test_extensions.py
@@ -1315,6 +1315,42 @@ $ARGUMENTS
assert not (skills_dir / "speckit-specify" / "SKILL.md").exists()
assert not (skills_dir / "speckit-shortcut" / "SKILL.md").exists()
+ def test_unregister_commands_handles_legacy_dot_notated_files(self, project_dir):
+ """Unregister should clean up both legacy dot-notated and new hyphenated files."""
+ # 1. Mock an agent that uses hyphenated/formatted names (e.g. Cline)
+ from specify_cli.agents import CommandRegistrar as AgentCommandRegistrar
+ registrar = AgentCommandRegistrar()
+
+ # We'll use "cline" since it has format_name
+ assert "cline" in registrar.AGENT_CONFIGS
+ cline_config = registrar.AGENT_CONFIGS["cline"]
+ cline_dir = project_dir / cline_config["dir"]
+ cline_dir.mkdir(parents=True, exist_ok=True)
+
+ # 2. Create both legacy and new files
+ # Command name: speckit.git.commit
+ # Formatted name: speckit-git-commit
+ cmd_name = "speckit.git.commit"
+ formatted_name = "speckit-git-commit"
+
+ legacy_file = cline_dir / f"{cmd_name}.md"
+ formatted_file = cline_dir / f"{formatted_name}.md"
+
+ legacy_file.write_text("legacy body")
+ formatted_file.write_text("formatted body")
+
+ assert legacy_file.exists()
+ assert formatted_file.exists()
+
+ # 3. Call unregister
+ registrar.unregister_commands({"cline": [cmd_name]}, project_dir)
+
+ # 4. Verify both are gone
+ assert not legacy_file.exists(), "Legacy dot-notated file should be removed"
+ assert (
+ not formatted_file.exists()
+ ), "Formatted hyphenated file should be removed"
+
def test_register_commands_for_all_agents_distinguishes_codex_from_amp(self, extension_dir, project_dir):
"""A Codex project under .agents/skills should not implicitly activate Amp."""
skills_dir = project_dir / ".agents" / "skills"
@@ -4616,6 +4652,43 @@ class TestHookInvocationRendering:
assert execution["command"] == "speckit.tasks"
assert execution["invocation"] == "$speckit-tasks"
+ def test_cline_hooks_render_hyphenated_invocation(self, project_dir):
+ """Cline projects should render /speckit-* invocations."""
+ init_options = project_dir / ".specify" / "init-options.json"
+ init_options.parent.mkdir(parents=True, exist_ok=True)
+ init_options.write_text(json.dumps({"ai": "cline"}))
+
+ hook_executor = HookExecutor(project_dir)
+ execution = hook_executor.execute_hook(
+ {
+ "extension": "test-ext",
+ "command": "speckit.tasks",
+ "optional": False,
+ }
+ )
+
+ assert execution["command"] == "speckit.tasks"
+ assert execution["invocation"] == "/speckit-tasks"
+
+ def test_cline_hooks_render_extension_command(self, project_dir):
+ """Cline projects should render /speckit-my-ext-cmd for extension hooks."""
+ init_options = project_dir / ".specify" / "init-options.json"
+ init_options.parent.mkdir(parents=True, exist_ok=True)
+ init_options.write_text(json.dumps({"ai": "cline"}))
+
+ hook_executor = HookExecutor(project_dir)
+ # Test with a non-speckit. command
+ execution = hook_executor.execute_hook(
+ {
+ "extension": "test-ext",
+ "command": "my-extension.do-something",
+ "optional": False,
+ }
+ )
+
+ assert execution["command"] == "my-extension.do-something"
+ assert execution["invocation"] == "/speckit-my-extension-do-something"
+
def test_non_skill_command_keeps_slash_invocation(self, project_dir):
"""Custom hook commands should keep slash invocation style."""
init_options = project_dir / ".specify" / "init-options.json"
@@ -4751,3 +4824,157 @@ class TestExtensionRemoveCLI:
)
assert "2 commands" in result.output
+
+
+class TestClineExtensionHyphenation:
+ """Test that Cline integration uses hyphenated commands and frontmatter references."""
+
+ def _setup_mock_extension(self, tmp_path, ai_name):
+ import yaml
+ import json
+
+ # 1. Setup mock project
+ project_dir = tmp_path / "project"
+ project_dir.mkdir()
+ (project_dir / ".specify").mkdir()
+
+ init_options = project_dir / ".specify" / "init-options.json"
+ init_options.write_text(json.dumps({"ai": ai_name}), encoding="utf-8")
+
+ if ai_name == "cline":
+ commands_dest_dir = project_dir / ".clinerules" / "workflows"
+ else:
+ commands_dest_dir = project_dir / ".agents" / "commands"
+ commands_dest_dir.mkdir(parents=True, exist_ok=True)
+
+ # 2. Setup mock extension directory
+ ext_dir = tmp_path / "mock-ext"
+ ext_dir.mkdir()
+
+ manifest_data = {
+ "schema_version": "1.0",
+ "extension": {
+ "id": "mock-ext",
+ "name": "Mock Extension",
+ "version": "1.0.0",
+ "description": f"Mock extension for {ai_name} tests",
+ "author": "Tester",
+ "repository": "https://github.com/test/mock-ext",
+ "license": "MIT",
+ },
+ "requires": {
+ "speckit_version": ">=0.1.0",
+ },
+ "provides": {
+ "commands": [
+ {
+ "name": "speckit.mock-ext.hello",
+ "file": "commands/hello.md",
+ "description": "Test hello command",
+ "aliases": ["speckit.mock-ext.greet"]
+ }
+ ]
+ }
+ }
+
+ with open(ext_dir / "extension.yml", "w", encoding="utf-8") as f:
+ yaml.dump(manifest_data, f)
+
+ commands_dir = ext_dir / "commands"
+ commands_dir.mkdir()
+
+ # Command file with dotted speckit references in frontmatter and body
+ cmd_content = """---
+description: "Test hello command"
+agent: speckit.tasks
+handoffs:
+ - agent: speckit.iterate.start
+ message: "Hand off to start"
+---
+
+# Test Hello Command
+
+Please refer to speckit.mock-ext.greet for instructions.
+$ARGUMENTS
+"""
+ (commands_dir / "hello.md").write_text(cmd_content, encoding="utf-8")
+
+ return project_dir, ext_dir, commands_dest_dir
+
+ def test_cline_extension_hyphenation(self, tmp_path):
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+ from specify_cli.agents import CommandRegistrar
+
+ project_dir, ext_dir, cline_workflows_dir = self._setup_mock_extension(tmp_path, "cline")
+
+ # 3. Run specify extension add
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir):
+ result = runner.invoke(
+ app, ["extension", "add", str(ext_dir), "--dev"], catch_exceptions=False
+ )
+
+ # Verify CLI printed hyphenated commands
+ # Note: We assert that the primary command 'speckit-mock-ext-hello' is printed,
+ # but we do not assert that the alias 'speckit-mock-ext-greet' is printed in the console
+ # because manifest.commands only lists primary commands.
+ assert "speckit-mock-ext-hello" in result.output
+ assert "speckit.mock-ext.hello" not in result.output
+
+ # Verify on-disk command names are hyphenated
+ hello_file = cline_workflows_dir / "speckit-mock-ext-hello.md"
+ greet_file = cline_workflows_dir / "speckit-mock-ext-greet.md"
+
+ assert hello_file.exists()
+ assert greet_file.exists()
+
+ # Verify frontmatter in the generated files is recursively hyphenated
+ hello_text = hello_file.read_text(encoding="utf-8")
+ hello_fm, hello_body = CommandRegistrar.parse_frontmatter(hello_text)
+ assert hello_fm["agent"] == "speckit-tasks"
+ assert hello_fm["handoffs"][0]["agent"] == "speckit-iterate-start"
+
+ # Verify body references are hyphenated for Cline
+ assert "speckit-mock-ext-greet" in hello_body
+ assert "speckit.mock-ext.greet" not in hello_body
+
+ def test_non_cline_extension_no_hyphenation(self, tmp_path):
+ from typer.testing import CliRunner
+ from unittest.mock import patch
+ from specify_cli import app
+ from specify_cli.agents import CommandRegistrar
+
+ project_dir, ext_dir, claude_commands_dir = self._setup_mock_extension(tmp_path, "claude")
+
+ # 3. Run specify extension add
+ runner = CliRunner()
+ with patch.object(Path, "cwd", return_value=project_dir):
+ result = runner.invoke(
+ app, ["extension", "add", str(ext_dir), "--dev"], catch_exceptions=False
+ )
+
+ # Verify CLI printed dotted commands
+ # Note: We assert that the primary command 'speckit.mock-ext.hello' is printed,
+ # but we do not assert that the alias 'speckit.mock-ext.greet' is printed in the console
+ # because manifest.commands only lists primary commands.
+ assert "speckit.mock-ext.hello" in result.output
+ assert "speckit-mock-ext-hello" not in result.output
+
+ # Verify on-disk command names are dotted
+ hello_file = claude_commands_dir / "speckit.mock-ext.hello.md"
+ greet_file = claude_commands_dir / "speckit.mock-ext.greet.md"
+
+ assert hello_file.exists()
+ assert greet_file.exists()
+
+ # Verify frontmatter references are still dotted
+ hello_text = hello_file.read_text(encoding="utf-8")
+ hello_fm, hello_body = CommandRegistrar.parse_frontmatter(hello_text)
+ assert hello_fm["agent"] == "speckit.tasks"
+ assert hello_fm["handoffs"][0]["agent"] == "speckit.iterate.start"
+
+ # Verify body references are still dotted for non-Cline
+ assert "speckit.mock-ext.greet" in hello_body
+ assert "speckit-mock-ext-greet" not in hello_body
diff --git a/tests/test_workflows.py b/tests/test_workflows.py
index 7995512d6..a9c8c4c60 100644
--- a/tests/test_workflows.py
+++ b/tests/test_workflows.py
@@ -520,6 +520,7 @@ class TestCommandStep:
assert result.output["integration"] == "gemini"
def test_step_override_model(self):
+ from unittest.mock import patch
from specify_cli.workflows.steps.command import CommandStep
from specify_cli.workflows.base import StepContext
@@ -531,10 +532,12 @@ class TestCommandStep:
"model": "opus-4",
"input": {},
}
- result = step.execute(config, ctx)
+ with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+ result = step.execute(config, ctx)
assert result.output["model"] == "opus-4"
def test_options_merge(self):
+ from unittest.mock import patch
from specify_cli.workflows.steps.command import CommandStep
from specify_cli.workflows.base import StepContext
@@ -546,7 +549,8 @@ class TestCommandStep:
"options": {"thinking-budget": 32768},
"input": {},
}
- result = step.execute(config, ctx)
+ with patch("specify_cli.workflows.steps.command.shutil.which", return_value=None):
+ result = step.execute(config, ctx)
assert result.output["options"]["max-tokens"] == 8000
assert result.output["options"]["thinking-budget"] == 32768