refactor: extension-based skill renderer (registry + Claude modules)

Made-with: Cursor

Author: Rohan-1920

src/specify_cli/core/renderer_extensions/__init__.py

@@ -0,0 +1,51 @@
+"""Extension registry for skill markdown post-processing.
+
+The core applies registered :class:`RendererExtension` instances in order.
+Concrete transforms (e.g. Claude-specific) live in separate modules outside
+this package's knowledge.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class SkillRenderContext:
+    """Per-file context passed to each extension."""
+
+    skill_path: Path
+
+
+@runtime_checkable
+class RendererExtension(Protocol):
+    """Post-process installed skill markdown."""
+
+    def transform(self, content: str, ctx: SkillRenderContext) -> str:
+        """Return *content* with this extension's transformation applied."""
+        ...
+
+
+class ExtensionRegistry:
+    """Ordered list of extensions applied sequentially."""
+
+    def __init__(self) -> None:
+        self._extensions: list[RendererExtension] = []
+
+    def register(self, extension: RendererExtension) -> None:
+        self._extensions.append(extension)
+
+    def apply(self, content: str, ctx: SkillRenderContext) -> str:
+        out = content
+        for ext in self._extensions:
+            out = ext.transform(out, ctx)
+        return out
+
+
+def apply_extensions(
+    content: str, ctx: SkillRenderContext, registry: ExtensionRegistry
+) -> str:
+    """Apply *registry* to *content* (single entry point for callers)."""
+    return registry.apply(content, ctx)

src/specify_cli/core/renderer_extensions/claude_skill.py

@@ -0,0 +1,160 @@
+"""Claude Code skill post-processing (frontmatter flags and argument hints)."""
+
+from __future__ import annotations
+
+import re
+
+from . import RendererExtension, SkillRenderContext
+
+# Note injected into hook sections so Claude maps dot-notation command
+# names (from extensions.yml) to the hyphenated skill names 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"
+)
+
+# Mapping of command template stem → argument-hint text shown inline
+# when a user invokes the slash command in Claude Code.
+ARGUMENT_HINTS: dict[str, str] = {
+    "specify": "Describe the feature you want to specify",
+    "plan": "Optional guidance for the planning phase",
+    "tasks": "Optional task generation constraints",
+    "implement": "Optional implementation guidance or task filter",
+    "analyze": "Optional focus areas for analysis",
+    "clarify": "Optional areas to clarify in the spec",
+    "constitution": "Principles or values for the project constitution",
+    "checklist": "Domain or focus area for the checklist",
+    "taskstoissues": "Optional filter or label for GitHub issues",
+}
+
+
+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,
+    )
+
+
+def inject_argument_hint(content: str, hint: str) -> str:
+    """Insert ``argument-hint`` after the first ``description:`` in YAML frontmatter.
+
+    Skips injection if ``argument-hint:`` already exists in the
+    frontmatter to avoid duplicate keys.
+    """
+    lines = content.splitlines(keepends=True)
+
+    dash_count = 0
+    for line in lines:
+        stripped = line.rstrip("\n\r")
+        if stripped == "---":
+            dash_count += 1
+            if dash_count == 2:
+                break
+            continue
+        if dash_count == 1 and stripped.startswith("argument-hint:"):
+            return content
+
+    out: list[str] = []
+    in_fm = False
+    dash_count = 0
+    injected = False
+    for line in lines:
+        stripped = line.rstrip("\n\r")
+        if stripped == "---":
+            dash_count += 1
+            in_fm = dash_count == 1
+            out.append(line)
+            continue
+        if in_fm and not injected and stripped.startswith("description:"):
+            out.append(line)
+            if line.endswith("\r\n"):
+                eol = "\r\n"
+            elif line.endswith("\n"):
+                eol = "\n"
+            else:
+                eol = ""
+            escaped = hint.replace("\\", "\\\\").replace('"', '\\"')
+            out.append(f'argument-hint: "{escaped}"{eol}')
+            injected = True
+            continue
+        out.append(line)
+    return "".join(out)
+
+
+def inject_frontmatter_flag(content: str, key: str, value: str = "true") -> str:
+    """Insert ``key: value`` before the closing ``---`` if not already present."""
+    lines = content.splitlines(keepends=True)
+
+    dash_count = 0
+    for line in lines:
+        stripped = line.rstrip("\n\r")
+        if stripped == "---":
+            dash_count += 1
+            if dash_count == 2:
+                break
+            continue
+        if dash_count == 1 and stripped.startswith(f"{key}:"):
+            return content
+
+    out: list[str] = []
+    dash_count = 0
+    injected = False
+    for line in lines:
+        stripped = line.rstrip("\n\r")
+        if stripped == "---":
+            dash_count += 1
+            if dash_count == 2 and not injected:
+                if line.endswith("\r\n"):
+                    eol = "\r\n"
+                elif line.endswith("\n"):
+                    eol = "\n"
+                else:
+                    eol = ""
+                out.append(f"{key}: {value}{eol}")
+                injected = True
+        out.append(line)
+    return "".join(out)
+
+
+class ClaudeSkillTransformExtension:
+    """Inject Claude skill frontmatter flags, hook note, and optional argument-hint."""
+
+    def transform(self, content: str, ctx: SkillRenderContext) -> str:
+        updated = inject_frontmatter_flag(content, "user-invocable")
+        updated = inject_frontmatter_flag(
+            updated, "disable-model-invocation", "false"
+        )
+        updated = inject_hook_command_note(updated)
+
+        skill_dir_name = ctx.skill_path.parent.name
+        stem = skill_dir_name
+        if stem.startswith("speckit-"):
+            stem = stem[len("speckit-") :]
+        hint = ARGUMENT_HINTS.get(stem, "")
+        if hint:
+            updated = inject_argument_hint(updated, hint)
+        return updated

src/specify_cli/core/renderer_extensions/question_render.py

@@ -0,0 +1,14 @@
+"""Fenced ``speckit:question-render`` → AskUserQuestion JSON block."""
+
+from __future__ import annotations
+
+from ..question_transformer import transform_question_block
+from . import RendererExtension, SkillRenderContext
+
+
+class FencedQuestionRenderExtension:
+    """Replace question-render marker blocks with JSON payloads."""
+
+    def transform(self, content: str, ctx: SkillRenderContext) -> str:
+        del ctx  # path-independent
+        return transform_question_block(content)