💫 Toolkit to help you get started with SDD or any other process!
feat: add argument-hint frontmatter to Claude Code commands (#1951) (#2059)
Quratulain-bilal10be4848684d
diff --git a/src/specify_cli/integrations/claude/__init__.py b/src/specify_cli/integrations/claude/__init__.pyindex 482572007..9eb321461 100644--- a/src/specify_cli/integrations/claude/__init__.py+++ b/src/specify_cli/integrations/claude/__init__.py@@ -10,6 +10,20 @@ import yamlfrom ..base import SkillsIntegrationfrom ..manifest import IntegrationManifest+# 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",+}+class ClaudeIntegration(SkillsIntegration):"""Integration for Claude Code skills."""@@ -30,10 +44,53 @@ class ClaudeIntegration(SkillsIntegration):}context_file = "CLAUDE.md"- def command_filename(self, template_name: str) -> str:- """Claude skills live at .claude/skills/<name>/SKILL.md."""- skill_name = f"speckit-{template_name.replace('.', '-')}"- return f"{skill_name}/SKILL.md"+ @staticmethod+ 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)++ # Pre-scan: bail out if argument-hint already present in frontmatter+ 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 # already present++ 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)+ # Preserve the exact line-ending style (\r\n vs \n)+ 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 _render_skill(self, template_name: str, frontmatter: dict[str, Any], body: str) -> str:"""Render a processed command template as a Claude skill."""@@ -54,6 +111,38 @@ class ClaudeIntegration(SkillsIntegration):self.key, name, description, source)+ @staticmethod+ def _inject_disable_model_invocation(content: str) -> str:+ """Insert ``disable-model-invocation: true`` before the closing ``---``."""+ lines = content.splitlines(keepends=True)++ # Pre-scan: bail out if already present in frontmatter+ 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("disable-model-invocation:"):+ return content++ # Inject before the closing --- of frontmatter+ 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:+ eol = "\r\n" if line.endswith("\r\n") else "\n"+ out.append(f"disable-model-invocation: true{eol}")+ injected = True+ out.append(line)+ return "".join(out)+def setup(self,project_root: Path,@@ -61,49 +150,38 @@ class ClaudeIntegration(SkillsIntegration):parsed_options: dict[str, Any] | None = None,**opts: Any,) -> list[Path]:- """Install Claude skills into .claude/skills."""- templates = self.list_command_templates()- if not templates:- return []-- project_root_resolved = project_root.resolve()- if manifest.project_root != project_root_resolved:- raise ValueError(- f"manifest.project_root ({manifest.project_root}) does not match "- f"project_root ({project_root_resolved})"- )-- dest = self.skills_dest(project_root).resolve()- try:- dest.relative_to(project_root_resolved)- except ValueError as exc:- raise ValueError(- f"Integration destination {dest} escapes "- f"project root {project_root_resolved}"- ) from exc- dest.mkdir(parents=True, exist_ok=True)-- script_type = opts.get("script_type", "sh")- arg_placeholder = self.registrar_config.get("args", "$ARGUMENTS")- from specify_cli.agents import CommandRegistrar- registrar = CommandRegistrar()- created: list[Path] = []-- for src_file in templates:- raw = src_file.read_text(encoding="utf-8")- processed = self.process_template(raw, self.key, script_type, arg_placeholder)- frontmatter, body = registrar.parse_frontmatter(processed)- if not isinstance(frontmatter, dict):- frontmatter = {}-- rendered = self._render_skill(src_file.stem, frontmatter, body)- dst_file = self.write_file_and_record(- rendered,- dest / self.command_filename(src_file.stem),- project_root,- manifest,- )- created.append(dst_file)-- created.extend(self.install_scripts(project_root, manifest))+ """Install Claude skills, then inject argument-hint and disable-model-invocation."""+ created = super().setup(project_root, manifest, parsed_options, **opts)++ # Post-process generated skill files+ skills_dir = self.skills_dest(project_root).resolve()++ for path in created:+ # Only touch SKILL.md files under the skills directory+ try:+ path.resolve().relative_to(skills_dir)+ except ValueError:+ continue+ if path.name != "SKILL.md":+ continue++ content_bytes = path.read_bytes()+ content = content_bytes.decode("utf-8")++ # Inject disable-model-invocation: true (Claude skills run only when invoked)+ updated = self._inject_disable_model_invocation(content)++ # Inject argument-hint if available for this skill+ skill_dir_name = path.parent.name # e.g. "speckit-plan"+ stem = skill_dir_name+ if stem.startswith("speckit-"):+ stem = stem[len("speckit-"):]+ hint = ARGUMENT_HINTS.get(stem, "")+ if hint:+ updated = self.inject_argument_hint(updated, hint)++ if updated != content:+ path.write_bytes(updated.encode("utf-8"))+ self.record_file_in_manifest(path, project_root, manifest)+return createddiff --git a/tests/integrations/test_integration_claude.py b/tests/integrations/test_integration_claude.pyindex 998485469..fe50eecc7 100644--- a/tests/integrations/test_integration_claude.py+++ b/tests/integrations/test_integration_claude.py@@ -8,6 +8,7 @@ import yamlfrom specify_cli.integrations import INTEGRATION_REGISTRY, get_integrationfrom specify_cli.integrations.base import IntegrationBase+from specify_cli.integrations.claude import ARGUMENT_HINTSfrom specify_cli.integrations.manifest import IntegrationManifest@@ -279,3 +280,119 @@ class TestClaudeIntegration:metadata = manager.registry.get("claude-skill-command")assert "speckit-research" in metadata.get("registered_skills", [])+++class TestClaudeArgumentHints:+ """Verify that argument-hint frontmatter is injected for Claude skills."""++ def test_all_skills_have_hints(self, tmp_path):+ """Every generated SKILL.md must contain an argument-hint line."""+ i = get_integration("claude")+ m = IntegrationManifest("claude", tmp_path)+ created = i.setup(tmp_path, m, script_type="sh")+ skill_files = [f for f in created if f.name == "SKILL.md"]+ assert len(skill_files) > 0+ for f in skill_files:+ content = f.read_text(encoding="utf-8")+ assert "argument-hint:" in content, (+ f"{f.parent.name}/SKILL.md is missing argument-hint frontmatter"+ )++ def test_hints_match_expected_values(self, tmp_path):+ """Each skill's argument-hint must match the expected text."""+ i = get_integration("claude")+ m = IntegrationManifest("claude", tmp_path)+ created = i.setup(tmp_path, m, script_type="sh")+ skill_files = [f for f in created if f.name == "SKILL.md"]+ for f in skill_files:+ # Extract stem: speckit-plan -> plan+ stem = f.parent.name+ if stem.startswith("speckit-"):+ stem = stem[len("speckit-"):]+ expected_hint = ARGUMENT_HINTS.get(stem)+ assert expected_hint is not None, (+ f"No expected hint defined for skill '{stem}'"+ )+ content = f.read_text(encoding="utf-8")+ assert f'argument-hint: "{expected_hint}"' in content, (+ f"{f.parent.name}/SKILL.md: expected hint '{expected_hint}' not found"+ )++ def test_hint_is_inside_frontmatter(self, tmp_path):+ """argument-hint must appear between the --- delimiters, not in the body."""+ i = get_integration("claude")+ m = IntegrationManifest("claude", tmp_path)+ created = i.setup(tmp_path, m, script_type="sh")+ skill_files = [f for f in created if f.name == "SKILL.md"]+ for f in skill_files:+ content = f.read_text(encoding="utf-8")+ parts = content.split("---", 2)+ assert len(parts) >= 3, f"No frontmatter in {f.parent.name}/SKILL.md"+ frontmatter = parts[1]+ body = parts[2]+ assert "argument-hint:" in frontmatter, (+ f"{f.parent.name}/SKILL.md: argument-hint not in frontmatter section"+ )+ assert "argument-hint:" not in body, (+ f"{f.parent.name}/SKILL.md: argument-hint leaked into body"+ )++ def test_hint_appears_after_description(self, tmp_path):+ """argument-hint must immediately follow the description line."""+ i = get_integration("claude")+ m = IntegrationManifest("claude", tmp_path)+ created = i.setup(tmp_path, m, script_type="sh")+ skill_files = [f for f in created if f.name == "SKILL.md"]+ for f in skill_files:+ content = f.read_text(encoding="utf-8")+ lines = content.splitlines()+ found_description = False+ for idx, line in enumerate(lines):+ if line.startswith("description:"):+ found_description = True+ assert idx + 1 < len(lines), (+ f"{f.parent.name}/SKILL.md: description is last line"+ )+ assert lines[idx + 1].startswith("argument-hint:"), (+ f"{f.parent.name}/SKILL.md: argument-hint does not follow description"+ )+ break+ assert found_description, (+ f"{f.parent.name}/SKILL.md: no description: line found in output"+ )++ def test_inject_argument_hint_only_in_frontmatter(self):+ """inject_argument_hint must not modify description: lines in the body."""+ from specify_cli.integrations.claude import ClaudeIntegration++ content = (+ "---\n"+ "description: My command\n"+ "---\n"+ "\n"+ "description: this is body text\n"+ )+ result = ClaudeIntegration.inject_argument_hint(content, "Test hint")+ lines = result.splitlines()+ hint_count = sum(1 for ln in lines if ln.startswith("argument-hint:"))+ assert hint_count == 1, (+ f"Expected exactly 1 argument-hint line, found {hint_count}"+ )++ def test_inject_argument_hint_skips_if_already_present(self):+ """inject_argument_hint must not duplicate if argument-hint already exists."""+ from specify_cli.integrations.claude import ClaudeIntegration++ content = (+ "---\n"+ "description: My command\n"+ 'argument-hint: "Existing hint"\n'+ "---\n"+ "\n"+ "Body text\n"+ )+ result = ClaudeIntegration.inject_argument_hint(content, "New hint")+ assert result == content, "Content should be unchanged when hint already exists"+ lines = result.splitlines()+ hint_count = sum(1 for ln in lines if ln.startswith("argument-hint:"))+ assert hint_count == 1