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

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

- Changed injected name field from 'speckit.{command}' to 'speckit-{command}'
- Keeps standard filename format 'speckit.{command}.md'
- Aligns with Forge's command naming convention requirements
- All tests pass

* feat(forge): centralize name formatting to fix extension/preset command names

Address PR feedback by centralizing Forge command name formatting to ensure
consistent hyphenated names across both core template setup and
extension/preset command registration.

Changes:
- Add format_forge_command_name() utility function in forge integration
- Update ForgeIntegration._apply_forge_transformations() to use centralized formatter
- Add _format_name_for_agent() helper in CommandRegistrar to apply agent-specific formatting
- Update CommandRegistrar.register_commands() to format names for Forge (both primary commands and aliases)
- Add comprehensive test coverage for the formatter and registrar behavior

Impact:
- Extension commands installed for Forge now use 'name: speckit-my-extension-example'
  instead of 'name: speckit.my-extension.example'
- Fixes ZSH/shell compatibility issues with dot notation in command names
- Maintains backward compatibility for all other agents (they continue using dot notation)
- Eliminates duplication between integration setup and registrar paths

Example transformation:
  Before: name: speckit.jira.sync-status  (breaks in ZSH/Forge)
  After:  name: speckit-jira-sync-status  (works everywhere)

Fixes inconsistency where core templates used hyphens but extension/preset
commands preserved dots, breaking Forge's naming requirements.

* refactor(forge): move name formatting logic to integration module

Move _format_name_for_agent function logic into Forge integration's
registrar_config as a 'format_name' callback, improving separation of
concerns and keeping Forge-specific logic within its integration module.

Changes:
- Remove _format_name_for_agent() from agents.py (shared module)
- Add 'format_name' callback to Forge's registrar_config pointing to format_forge_command_name
- Update CommandRegistrar to use format_name callback when available
- Maintains same behavior: Forge commands use hyphenated names, others use dot notation

Benefits:
- Better encapsulation: Forge-specific logic lives in forge integration
- More extensible: Other integrations can provide custom formatters via registrar_config
- Cleaner separation: agents.py doesn't need to know about specific agent requirements

* fix(forge): make format_forge_command_name idempotent

Handle already-hyphenated names (speckit-foo) to prevent double-prefixing
(speckit-speckit-foo). The function now returns already-formatted names
unchanged, making it safe to call multiple times.

Changes:
- Add early return for names starting with 'speckit-'
- Update docstring to clarify accepted input formats
- Add examples showing idempotent behavior
- Add test coverage for idempotent behavior

Examples:
  format_forge_command_name('speckit-plan') -> 'speckit-plan' (unchanged)
  format_forge_command_name('speckit.plan') -> 'speckit-plan' (converted)
  format_forge_command_name('plan') -> 'speckit-plan' (prefixed)

* test(forge): strengthen name field assertions and clarify comments

Improve test_name_field_uses_hyphenated_format to fail loudly when
the name field is missing instead of silently passing.

Changes:
- Add explicit assertion that name_match is not None before validating value
- Ensures test fails if regex doesn't match (e.g., frontmatter rendering changes)
- Clarify Claude comment: it doesn't use inject_name path but SKILL.md
  frontmatter still includes hyphenated name via build_skill_frontmatter()

Before: Test would silently pass if 'name:' field was missing from frontmatter
After: Test explicitly asserts field presence before validating format

* docs(forge): clarify frontmatter name requirement and improve test isolation

Fix misleading docstring and improve test to properly validate that the
format_name callback is Forge-specific.

Changes to src/specify_cli/integrations/forge/__init__.py:
- Reword module docstring to clarify the requirement is specifically for
  the frontmatter 'name' field value, not command files or invocation
- Before: 'Requires hyphenated command names ... instead of dot notation'
  (implied dot notation unsupported overall)
- After: 'Uses a hyphenated frontmatter name value ... for shell compatibility'
  (clarifies it's the frontmatter field, and Forge still supports dot filenames)

Changes to tests/integrations/test_integration_forge.py:
- Replace Claude with Windsurf in test_registrar_does_not_affect_other_agents
- Claude uses build_skill_frontmatter() which always includes hyphenated names,
  so testing it didn't validate that format_name callback is Forge-only
- Windsurf is a standard markdown agent without inject_name
- Now asserts NO 'name:' field is present, proving format_name isn't invoked
- This properly validates the callback mechanism is isolated to Forge

* test(forge): use parse_frontmatter for precise YAML validation

Replace regex and string searches with CommandRegistrar.parse_frontmatter()
to validate only YAML frontmatter, not entire file content. Prevents false
positives if command body contains 'name:' lines.

Changes:
- test_forge_specific_transformations: Parse frontmatter dict instead of string search
- test_name_field_uses_hyphenated_format: Replace regex with frontmatter parsing
- test_registrar_formats_extension_command_names_for_forge: Use dict validation
- test_registrar_formats_alias_names_for_forge: Use dict validation

Benefits: More precise, robust against body content, better error messages,
consistent with existing codebase utilities.

---------

Co-authored-by: ericnoam <eric.rodriguez@leovegas.com>

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