Skip to content

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

fix(claude): make argument-hint injection fold-aware for long descriptions (#4045)

chelsealongbd595cf838cc
diff --git a/src/specify_cli/integrations/claude/__init__.py b/src/specify_cli/integrations/claude/__init__.py
index 39732794a..2ce7fb6dc 100644
--- a/src/specify_cli/integrations/claude/__init__.py
+++ b/src/specify_cli/integrations/claude/__init__.py
@@ -67,7 +67,16 @@ class ClaudeIntegration(SkillsIntegration):
@staticmethod
def inject_argument_hint(content: str, hint: str) -> str:
- """Insert ``argument-hint`` after the first ``description:`` in YAML frontmatter.
+ """Insert ``argument-hint`` after the ``description:`` scalar in YAML frontmatter.
+
+ A long ``description`` gets folded by the YAML dumper across
+ indented continuation lines (plain or quoted), and an embedded
+ paragraph break can add unindented blank lines inside a quoted
+ scalar. Inserting the new line right after the *first* line of
+ that scalar β€” instead of after the whole scalar β€” either produces
+ invalid YAML or gets silently absorbed into the description
+ string (#4044), so every continuation line (indented, or blank)
+ is skipped first.
Skips injection if ``argument-hint:`` already exists in the
frontmatter to avoid duplicate keys.
@@ -90,15 +99,29 @@ class ClaudeIntegration(SkillsIntegration):
in_fm = False
dash_count = 0
injected = False
- for line in lines:
+ i = 0
+ n = len(lines)
+ while i < n:
+ line = lines[i]
stripped = line.rstrip("\n\r")
if stripped == "---":
dash_count += 1
in_fm = dash_count == 1
out.append(line)
+ i += 1
continue
if in_fm and not injected and stripped.startswith("description:"):
out.append(line)
+ i += 1
+ # Skip past folded/quoted continuation lines of the scalar
+ # before inserting, so the new key lands after it ends.
+ # Blank lines count too: PyYAML emits unindented blank
+ # lines for embedded "\n\n" inside a quoted scalar.
+ while i < n and (
+ lines[i][:1] in (" ", "\t") or lines[i].rstrip("\r\n") == ""
+ ):
+ out.append(lines[i])
+ i += 1
# Preserve the exact line-ending style (\r\n vs \n)
if line.endswith("\r\n"):
eol = "\r\n"
@@ -111,6 +134,7 @@ class ClaudeIntegration(SkillsIntegration):
injected = True
continue
out.append(line)
+ i += 1
return "".join(out)
def _render_skill(self, template_name: str, frontmatter: dict[str, Any], body: str) -> str:
diff --git a/tests/integrations/test_integration_claude.py b/tests/integrations/test_integration_claude.py
index 7916fdeba..3718af974 100644
--- a/tests/integrations/test_integration_claude.py
+++ b/tests/integrations/test_integration_claude.py
@@ -451,6 +451,93 @@ class TestClaudeArgumentHints:
hint_count = sum(1 for ln in lines if ln.startswith("argument-hint:"))
assert hint_count == 1
+ def test_inject_argument_hint_survives_folded_description(self):
+ """A long description folded across lines must not corrupt the YAML (#4044).
+
+ A description long enough for the YAML dumper to fold it into a
+ multi-line plain scalar previously had ``argument-hint:`` spliced
+ into the *middle* of that scalar, producing invalid YAML.
+ """
+ from specify_cli.integrations.claude import ClaudeIntegration
+
+ frontmatter = {
+ "name": "speckit-specify",
+ "description": (
+ "Create or update the feature specification from a natural "
+ "language feature description. Also accepts an issue URL "
+ "resolved via gh CLI (demo customization)."
+ ),
+ "compatibility": "Requires spec-kit project structure with .specify/ directory",
+ }
+ frontmatter_text = yaml.safe_dump(
+ frontmatter, sort_keys=False, allow_unicode=True
+ ).strip()
+ content = f"---\n{frontmatter_text}\n---\n\nBody text\n"
+ assert "\n " in content, "fixture description must actually fold across lines"
+
+ result = ClaudeIntegration.inject_argument_hint(content, "Describe the feature")
+
+ parsed = yaml.safe_load(result.split("---")[1])
+ assert parsed["argument-hint"] == "Describe the feature"
+ assert parsed["description"] == frontmatter["description"]
+
+ def test_inject_argument_hint_survives_quoted_folded_description(self):
+ """A folded description forced into quotes must not absorb the hint (#4044)."""
+ from specify_cli.integrations.claude import ClaudeIntegration
+
+ frontmatter = {
+ "name": "speckit-specify",
+ "description": (
+ "Create or update the feature specification from a natural "
+ "language feature description. Also accepts a GitHub "
+ "issue/PR URL or #N reference resolved via gh CLI (demo)."
+ ),
+ "compatibility": "Requires spec-kit project structure with .specify/ directory",
+ }
+ frontmatter_text = yaml.safe_dump(
+ frontmatter, sort_keys=False, allow_unicode=True
+ ).strip()
+ content = f"---\n{frontmatter_text}\n---\n\nBody text\n"
+ assert "\n " in content, "fixture description must actually fold across lines"
+
+ result = ClaudeIntegration.inject_argument_hint(content, "Describe the feature")
+
+ parsed = yaml.safe_load(result.split("---")[1])
+ assert parsed["argument-hint"] == "Describe the feature"
+ assert parsed["description"] == frontmatter["description"]
+
+ def test_inject_argument_hint_survives_multi_paragraph_description(self):
+ """A description with an embedded blank line must not absorb the hint.
+
+ PyYAML serializes an embedded ``\\n\\n`` inside a quoted scalar as
+ unindented blank lines, not indented ones, so a fix that only skips
+ indented continuation lines still fails on this case.
+ """
+ from specify_cli.integrations.claude import ClaudeIntegration
+
+ frontmatter = {
+ "name": "speckit-specify",
+ "description": (
+ "First paragraph of a fairly long description that will "
+ "need to wrap across multiple lines when dumped by PyYAML."
+ "\n\n"
+ "Second paragraph continues the description after a blank "
+ "line separator to force embedded newlines in the scalar."
+ ),
+ "compatibility": "Requires spec-kit project structure with .specify/ directory",
+ }
+ frontmatter_text = yaml.safe_dump(
+ frontmatter, sort_keys=False, allow_unicode=True
+ ).strip()
+ content = f"---\n{frontmatter_text}\n---\n\nBody text\n"
+ assert "\n\n" in frontmatter_text, "fixture must produce a blank continuation line"
+
+ result = ClaudeIntegration.inject_argument_hint(content, "Describe the feature")
+
+ parsed = yaml.safe_load(result.split("---")[1])
+ assert parsed["argument-hint"] == "Describe the feature"
+ assert parsed["description"] == frontmatter["description"]
+
class TestClaudeDisableModelInvocation:
"""Verify disable-model-invocation is false for Claude skills."""