Skip to content

💫 Toolkit to help you get started with SDD or any other process!

fix(forge): use hyphen notation in frontmatter name field (#2075)

toxicafunk71143598bec2
diff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.py
index 4b869283c..ec7af8876 100644
--- a/src/specify_cli/agents.py
+++ b/src/specify_cli/agents.py
@@ -420,7 +420,9 @@ class CommandRegistrar:
frontmatter.pop(key, None)
if agent_config.get("inject_name") and not frontmatter.get("name"):
- frontmatter["name"] = cmd_name
+ # Use custom name formatter if provided (e.g., Forge's hyphenated format)
+ format_name = agent_config.get("format_name")
+ frontmatter["name"] = format_name(cmd_name) if format_name else cmd_name
body = self._convert_argument_placeholder(
body, "$ARGUMENTS", agent_config["args"]
@@ -454,7 +456,9 @@ class CommandRegistrar:
# For agents with inject_name, render with alias-specific frontmatter
if agent_config.get("inject_name"):
alias_frontmatter = deepcopy(frontmatter)
- alias_frontmatter["name"] = alias
+ # Use custom name formatter if provided (e.g., Forge's hyphenated format)
+ format_name = agent_config.get("format_name")
+ alias_frontmatter["name"] = format_name(alias) if format_name else alias
if agent_config["extension"] == "/SKILL.md":
alias_output = self.render_skill_command(
diff --git a/src/specify_cli/integrations/forge/__init__.py b/src/specify_cli/integrations/forge/__init__.py
index e3d534727..e1c4d9da6 100644
--- a/src/specify_cli/integrations/forge/__init__.py
+++ b/src/specify_cli/integrations/forge/__init__.py
@@ -4,6 +4,7 @@ Forge has several unique behaviors compared to standard markdown agents:
- Uses `{{parameters}}` instead of `$ARGUMENTS` for argument passing
- Strips `handoffs` frontmatter key (Claude Code feature that causes Forge to hang)
- Injects `name` field into frontmatter when missing
+- Uses a hyphenated frontmatter `name` value (e.g., `speckit-foo-bar`) for shell compatibility, especially with ZSH
"""
from __future__ import annotations
@@ -15,6 +16,52 @@ from ..base import MarkdownIntegration
from ..manifest import IntegrationManifest
+def format_forge_command_name(cmd_name: str) -> str:
+ """Convert command name to Forge-compatible hyphenated format.
+
+ Forge requires command names to use hyphens instead of dots for
+ compatibility with ZSH and other shells. This function converts
+ dot-notation command names to hyphenated format.
+
+ The function is idempotent: already-formatted names are returned unchanged.
+
+ Examples:
+ >>> format_forge_command_name("plan")
+ 'speckit-plan'
+ >>> format_forge_command_name("speckit.plan")
+ 'speckit-plan'
+ >>> format_forge_command_name("speckit-plan")
+ 'speckit-plan'
+ >>> format_forge_command_name("speckit.my-extension.example")
+ 'speckit-my-extension-example'
+ >>> format_forge_command_name("speckit-my-extension-example")
+ 'speckit-my-extension-example'
+ >>> format_forge_command_name("speckit.jira.sync-status")
+ 'speckit-jira-sync-status'
+
+ 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
+ """
+ # Already in hyphenated format - return as-is (idempotent)
+ if cmd_name.startswith("speckit-"):
+ return cmd_name
+
+ # Strip 'speckit.' prefix if present
+ short_name = cmd_name
+ if short_name.startswith("speckit."):
+ short_name = short_name[len("speckit."):]
+
+ # Replace all dots with hyphens
+ short_name = short_name.replace(".", "-")
+
+ # Return with 'speckit-' prefix
+ return f"speckit-{short_name}"
+
+
class ForgeIntegration(MarkdownIntegration):
"""Integration for Forge (forgecode.dev).
@@ -39,6 +86,7 @@ class ForgeIntegration(MarkdownIntegration):
"extension": ".md",
"strip_frontmatter_keys": ["handoffs"],
"inject_name": True,
+ "format_name": format_forge_command_name, # Custom name formatter
}
context_file = "AGENTS.md"
@@ -106,7 +154,7 @@ class ForgeIntegration(MarkdownIntegration):
"""Apply Forge-specific transformations to processed content.
1. Strip 'handoffs' frontmatter key (from Claude Code templates; incompatible with Forge)
- 2. Inject 'name' field if missing
+ 2. Inject 'name' field if missing (using hyphenated format)
"""
# Parse frontmatter
lines = content.split('\n')
@@ -143,11 +191,11 @@ class ForgeIntegration(MarkdownIntegration):
filtered_frontmatter.append(line)
- # 2. Inject 'name' field if missing
+ # 2. Inject 'name' field if missing (using centralized formatter)
has_name = any(line.strip().startswith('name:') for line in filtered_frontmatter)
if not has_name:
- # Use the template name as the command name (e.g., "plan" -> "speckit.plan")
- cmd_name = f"speckit.{template_name}"
+ # Use centralized formatter to ensure consistent hyphenated format
+ cmd_name = format_forge_command_name(template_name)
filtered_frontmatter.insert(0, f'name: {cmd_name}')
# Reconstruct content
diff --git a/tests/integrations/test_integration_forge.py b/tests/integrations/test_integration_forge.py
index 10905723f..7affd0d16 100644
--- a/tests/integrations/test_integration_forge.py
+++ b/tests/integrations/test_integration_forge.py
@@ -2,6 +2,47 @@
from specify_cli.integrations import get_integration
from specify_cli.integrations.manifest import IntegrationManifest
+from specify_cli.integrations.forge import format_forge_command_name
+
+
+class TestForgeCommandNameFormatter:
+ """Test the centralized Forge command name formatter."""
+
+ def test_simple_name_without_prefix(self):
+ """Test formatting a simple name without 'speckit.' prefix."""
+ assert format_forge_command_name("plan") == "speckit-plan"
+ assert format_forge_command_name("tasks") == "speckit-tasks"
+ assert format_forge_command_name("specify") == "speckit-specify"
+
+ def test_name_with_speckit_prefix(self):
+ """Test formatting a name that already has 'speckit.' prefix."""
+ assert format_forge_command_name("speckit.plan") == "speckit-plan"
+ assert format_forge_command_name("speckit.tasks") == "speckit-tasks"
+
+ def test_extension_command_name(self):
+ """Test formatting extension command names with dots."""
+ assert format_forge_command_name("speckit.my-extension.example") == "speckit-my-extension-example"
+ assert format_forge_command_name("my-extension.example") == "speckit-my-extension-example"
+
+ def test_complex_nested_name(self):
+ """Test formatting deeply nested command names."""
+ assert format_forge_command_name("speckit.jira.sync-status") == "speckit-jira-sync-status"
+ assert format_forge_command_name("speckit.foo.bar.baz") == "speckit-foo-bar-baz"
+
+ def test_name_with_hyphens_preserved(self):
+ """Test that existing hyphens are preserved."""
+ assert format_forge_command_name("my-extension") == "speckit-my-extension"
+ assert format_forge_command_name("speckit.my-ext.test-cmd") == "speckit-my-ext-test-cmd"
+
+ def test_alias_formatting(self):
+ """Test formatting alias names."""
+ assert format_forge_command_name("speckit.my-extension.example-short") == "speckit-my-extension-example-short"
+
+ def test_idempotent_already_hyphenated(self):
+ """Test that already-hyphenated names are returned unchanged (idempotent)."""
+ assert format_forge_command_name("speckit-plan") == "speckit-plan"
+ assert format_forge_command_name("speckit-my-extension-example") == "speckit-my-extension-example"
+ assert format_forge_command_name("speckit-jira-sync-status") == "speckit-jira-sync-status"
class TestForgeIntegration:
@@ -123,19 +164,22 @@ class TestForgeIntegration:
def test_forge_specific_transformations(self, tmp_path):
"""Test Forge-specific processing: name injection and handoffs stripping."""
from specify_cli.integrations.forge import ForgeIntegration
+ from specify_cli.agents import CommandRegistrar
forge = ForgeIntegration()
m = IntegrationManifest("forge", tmp_path)
forge.setup(tmp_path, m)
commands_dir = tmp_path / ".forge" / "commands"
+ registrar = CommandRegistrar()
for cmd_file in commands_dir.glob("speckit.*.md"):
content = cmd_file.read_text(encoding="utf-8")
+ frontmatter, _ = registrar.parse_frontmatter(content)
# Check that name field is injected in frontmatter
- assert "\nname: " in content, f"{cmd_file.name} missing injected 'name' field"
+ assert "name" in frontmatter, f"{cmd_file.name} missing injected 'name' field in frontmatter"
# Check that handoffs frontmatter key is stripped
- assert "\nhandoffs:" not in content, f"{cmd_file.name} has unstripped 'handoffs' key"
+ assert "handoffs" not in frontmatter, f"{cmd_file.name} has unstripped 'handoffs' key in frontmatter"
def test_uses_parameters_placeholder(self, tmp_path):
"""Verify Forge replaces $ARGUMENTS with {{parameters}} in generated files."""
@@ -168,3 +212,181 @@ class TestForgeIntegration:
assert "{{parameters}}" in content, (
"checklist should contain {{parameters}} in User Input section"
)
+
+ def test_name_field_uses_hyphenated_format(self, tmp_path):
+ """Verify that injected name fields use hyphenated format (speckit-plan, not speckit.plan)."""
+ from specify_cli.integrations.forge import ForgeIntegration
+ from specify_cli.agents import CommandRegistrar
+ forge = ForgeIntegration()
+ m = IntegrationManifest("forge", tmp_path)
+ forge.setup(tmp_path, m)
+ commands_dir = tmp_path / ".forge" / "commands"
+
+ # Check that name fields use hyphenated format
+ registrar = CommandRegistrar()
+ for cmd_file in commands_dir.glob("speckit.*.md"):
+ content = cmd_file.read_text(encoding="utf-8")
+ # Extract the name field from frontmatter using the parser
+ frontmatter, _ = registrar.parse_frontmatter(content)
+ assert "name" in frontmatter, (
+ f"{cmd_file.name} missing injected 'name' field in frontmatter"
+ )
+ name_value = frontmatter["name"]
+ # Name should use hyphens, not dots
+ assert "." not in name_value, (
+ f"{cmd_file.name} has name field with dots: {name_value} "
+ f"(should use hyphens for Forge/ZSH compatibility)"
+ )
+ assert name_value.startswith("speckit-"), (
+ f"{cmd_file.name} name field should start with 'speckit-': {name_value}"
+ )
+
+
+class TestForgeCommandRegistrar:
+ """Test CommandRegistrar's Forge-specific name formatting."""
+
+ def test_registrar_formats_extension_command_names_for_forge(self, tmp_path):
+ """Verify CommandRegistrar converts dot notation to hyphens for Forge."""
+ from specify_cli.agents import CommandRegistrar
+
+ # Create a mock extension command file
+ ext_dir = tmp_path / "extension"
+ ext_dir.mkdir()
+ cmd_dir = ext_dir / "commands"
+ cmd_dir.mkdir()
+
+ # Create a test command with dot notation name
+ cmd_file = cmd_dir / "example.md"
+ cmd_file.write_text(
+ "---\n"
+ "description: Test extension command\n"
+ "---\n\n"
+ "Test content with $ARGUMENTS\n",
+ encoding="utf-8"
+ )
+
+ # Register with Forge
+ registrar = CommandRegistrar()
+ commands = [
+ {
+ "name": "speckit.my-extension.example",
+ "file": "commands/example.md"
+ }
+ ]
+
+ registered = registrar.register_commands(
+ "forge",
+ commands,
+ "test-extension",
+ ext_dir,
+ tmp_path
+ )
+
+ # Verify registration succeeded
+ 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"
+ assert forge_cmd.exists()
+
+ content = forge_cmd.read_text(encoding="utf-8")
+ # Parse frontmatter to validate name field precisely
+ frontmatter, _ = registrar.parse_frontmatter(content)
+ assert "name" in frontmatter, "name field should be injected in frontmatter"
+ # Name field should use hyphens, not dots
+ assert frontmatter["name"] == "speckit-my-extension-example"
+
+ def test_registrar_formats_alias_names_for_forge(self, tmp_path):
+ """Verify CommandRegistrar converts alias names to hyphens for Forge."""
+ from specify_cli.agents import CommandRegistrar
+
+ # Create a mock extension command file
+ ext_dir = tmp_path / "extension"
+ ext_dir.mkdir()
+ cmd_dir = ext_dir / "commands"
+ cmd_dir.mkdir()
+
+ cmd_file = cmd_dir / "example.md"
+ cmd_file.write_text(
+ "---\n"
+ "description: Test command with alias\n"
+ "---\n\n"
+ "Test content\n",
+ encoding="utf-8"
+ )
+
+ # Register with Forge including an alias
+ registrar = CommandRegistrar()
+ commands = [
+ {
+ "name": "speckit.my-extension.example",
+ "file": "commands/example.md",
+ "aliases": ["speckit.my-extension.ex"]
+ }
+ ]
+
+ registrar.register_commands(
+ "forge",
+ commands,
+ "test-extension",
+ ext_dir,
+ tmp_path
+ )
+
+ # Check the alias file has hyphenated name in frontmatter
+ alias_file = tmp_path / ".forge" / "commands" / "speckit.my-extension.ex.md"
+ assert alias_file.exists()
+
+ content = alias_file.read_text(encoding="utf-8")
+ # Parse frontmatter to validate alias name field precisely
+ frontmatter, _ = registrar.parse_frontmatter(content)
+ assert "name" in frontmatter, "name field should be injected in alias frontmatter"
+ # Alias name field should also use hyphens
+ assert frontmatter["name"] == "speckit-my-extension-ex"
+
+ def test_registrar_does_not_affect_other_agents(self, tmp_path):
+ """Verify format_name callback is Forge-specific and doesn't affect other agents."""
+ from specify_cli.agents import CommandRegistrar
+
+ # Create a mock extension command file
+ ext_dir = tmp_path / "extension"
+ ext_dir.mkdir()
+ cmd_dir = ext_dir / "commands"
+ cmd_dir.mkdir()
+
+ cmd_file = cmd_dir / "example.md"
+ cmd_file.write_text(
+ "---\n"
+ "description: Test command\n"
+ "---\n\n"
+ "Test content with $ARGUMENTS\n",
+ encoding="utf-8"
+ )
+
+ # Register with Windsurf (standard markdown agent without inject_name)
+ registrar = CommandRegistrar()
+ commands = [
+ {
+ "name": "speckit.my-extension.example",
+ "file": "commands/example.md"
+ }
+ ]
+
+ registrar.register_commands(
+ "windsurf",
+ commands,
+ "test-extension",
+ ext_dir,
+ tmp_path
+ )
+
+ # Windsurf uses standard markdown format without name injection.
+ # The format_name callback should not be invoked for non-Forge agents.
+ windsurf_cmd = tmp_path / ".windsurf" / "workflows" / "speckit.my-extension.example.md"
+ assert windsurf_cmd.exists()
+
+ content = windsurf_cmd.read_text(encoding="utf-8")
+ # Windsurf should NOT have a name field injected
+ assert "name:" not in content, (
+ "Windsurf should not inject name field - format_name callback should be Forge-only"
+ )