Skip to content

Commit 725cdd9

Browse files
Quratulain-bilalclaude
authored andcommitted
feat: add argument-hint frontmatter to Claude Code commands (github#1951) (github#2059)
* feat: add argument-hint frontmatter to Claude Code commands (github#1951) Inject argument-hint into YAML frontmatter for Claude agent only during release package generation. Templates remain agent-agnostic; hints are added on the fly in generate_commands() when agent is "claude". Closes github#1951 Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix: scope argument-hint injection to YAML frontmatter only Addresses Copilot review: the awk/regex matched description: anywhere in the file. Now both bash and PowerShell track frontmatter boundaries (--- delimiters) and only inject argument-hint after the first description: inside the frontmatter block. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * feat: add argument-hint to Claude integration + tests - Override setup() in ClaudeIntegration to inject argument-hint into YAML frontmatter after description: line, scoped to frontmatter only - Add ARGUMENT_HINTS mapping for all 9 commands - Add tests: hint presence, correct values, frontmatter scoping, ordering after description, and body-safety check Addresses maintainer feedback to cover the new integrations system in src/specify_cli/integrations/claude/__init__.py with tests in tests/integrations/test_integration_claude.py Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix: address Copilot review feedback on Claude integration - Remove unused `import re` - Skip injection if argument-hint already exists in frontmatter - Add found_description assertion to test_hint_appears_after_description - Add test_inject_argument_hint_skips_if_already_present test Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * refactor: delegate to super().setup() and post-process for hints - Eliminates setup() duplication by calling super().setup() then post-processing command files to inject argument-hint - Fixes EOL preservation to correctly detect \r\n vs \n - No drift risk if MarkdownIntegration.setup() changes Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * fix: use read_bytes/write_bytes for platform-stable EOL handling Address Copilot review: avoid platform newline translation by using read_bytes()/write_bytes() instead of read_text()/write_text() when post-processing SKILL.md files for argument-hint injection. * fix: re-record manifest hash after hint injection, quote hint values - Re-record file hash in manifest after writing argument-hint so check_modified()/uninstall stays in sync - Double-quote argument-hint values to match SKILL.md frontmatter style - Update tests to expect quoted hint values * fix: inject disable-model-invocation into Claude skill frontmatter --------- Co-authored-by: Claude Sonnet 4.6 <[email protected]>
1 parent 4f5eb84 commit 725cdd9

2 files changed

Lines changed: 551 additions & 7 deletions

File tree

‎src/specify_cli/integrations/claude/__init__.py‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,20 @@
55

66
from ..base import MarkdownIntegration
77

8+
# Mapping of command template stem → argument-hint text shown inline
9+
# when a user invokes the slash command in Claude Code.
10+
ARGUMENT_HINTS: dict[str, str] = {
11+
"specify": "Describe the feature you want to specify",
12+
"plan": "Optional guidance for the planning phase",
13+
"tasks": "Optional task generation constraints",
14+
"implement": "Optional implementation guidance or task filter",
15+
"analyze": "Optional focus areas for analysis",
16+
"clarify": "Optional areas to clarify in the spec",
17+
"constitution": "Principles or values for the project constitution",
18+
"checklist": "Domain or focus area for the checklist",
19+
"taskstoissues": "Optional filter or label for GitHub issues",
20+
}
21+
822

923
class ClaudeIntegration(MarkdownIntegration):
1024
key = "claude"
@@ -22,3 +36,145 @@ class ClaudeIntegration(MarkdownIntegration):
2236
"extension": ".md",
2337
}
2438
context_file = "CLAUDE.md"
39+
40+
@staticmethod
41+
def inject_argument_hint(content: str, hint: str) -> str:
42+
"""Insert ``argument-hint`` after the first ``description:`` in YAML frontmatter.
43+
44+
Skips injection if ``argument-hint:`` already exists in the
45+
frontmatter to avoid duplicate keys.
46+
"""
47+
lines = content.splitlines(keepends=True)
48+
49+
# Pre-scan: bail out if argument-hint already present in frontmatter
50+
dash_count = 0
51+
for line in lines:
52+
stripped = line.rstrip("\n\r")
53+
if stripped == "---":
54+
dash_count += 1
55+
if dash_count == 2:
56+
break
57+
continue
58+
if dash_count == 1 and stripped.startswith("argument-hint:"):
59+
return content # already present
60+
61+
out: list[str] = []
62+
in_fm = False
63+
dash_count = 0
64+
injected = False
65+
for line in lines:
66+
stripped = line.rstrip("\n\r")
67+
if stripped == "---":
68+
dash_count += 1
69+
in_fm = dash_count == 1
70+
out.append(line)
71+
continue
72+
if in_fm and not injected and stripped.startswith("description:"):
73+
out.append(line)
74+
# Preserve the exact line-ending style (\r\n vs \n)
75+
if line.endswith("\r\n"):
76+
eol = "\r\n"
77+
elif line.endswith("\n"):
78+
eol = "\n"
79+
else:
80+
eol = ""
81+
escaped = hint.replace("\\", "\\\\").replace('"', '\\"')
82+
out.append(f'argument-hint: "{escaped}"{eol}')
83+
injected = True
84+
continue
85+
out.append(line)
86+
return "".join(out)
87+
88+
def _render_skill(self, template_name: str, frontmatter: dict[str, Any], body: str) -> str:
89+
"""Render a processed command template as a Claude skill."""
90+
skill_name = f"speckit-{template_name.replace('.', '-')}"
91+
description = frontmatter.get(
92+
"description",
93+
f"Spec-kit workflow command: {template_name}",
94+
)
95+
skill_frontmatter = self._build_skill_fm(
96+
skill_name, description, f"templates/commands/{template_name}.md"
97+
)
98+
frontmatter_text = yaml.safe_dump(skill_frontmatter, sort_keys=False).strip()
99+
return f"---\n{frontmatter_text}\n---\n\n{body.strip()}\n"
100+
101+
def _build_skill_fm(self, name: str, description: str, source: str) -> dict:
102+
from specify_cli.agents import CommandRegistrar
103+
return CommandRegistrar.build_skill_frontmatter(
104+
self.key, name, description, source
105+
)
106+
107+
@staticmethod
108+
def _inject_disable_model_invocation(content: str) -> str:
109+
"""Insert ``disable-model-invocation: true`` before the closing ``---``."""
110+
lines = content.splitlines(keepends=True)
111+
112+
# Pre-scan: bail out if already present in frontmatter
113+
dash_count = 0
114+
for line in lines:
115+
stripped = line.rstrip("\n\r")
116+
if stripped == "---":
117+
dash_count += 1
118+
if dash_count == 2:
119+
break
120+
continue
121+
if dash_count == 1 and stripped.startswith("disable-model-invocation:"):
122+
return content
123+
124+
# Inject before the closing --- of frontmatter
125+
out: list[str] = []
126+
dash_count = 0
127+
injected = False
128+
for line in lines:
129+
stripped = line.rstrip("\n\r")
130+
if stripped == "---":
131+
dash_count += 1
132+
if dash_count == 2 and not injected:
133+
eol = "\r\n" if line.endswith("\r\n") else "\n"
134+
out.append(f"disable-model-invocation: true{eol}")
135+
injected = True
136+
out.append(line)
137+
return "".join(out)
138+
139+
def setup(
140+
self,
141+
project_root: Path,
142+
manifest: IntegrationManifest,
143+
parsed_options: dict[str, Any] | None = None,
144+
**opts: Any,
145+
) -> list[Path]:
146+
"""Install Claude skills, then inject argument-hint and disable-model-invocation."""
147+
created = super().setup(project_root, manifest, parsed_options, **opts)
148+
149+
# Post-process generated skill files
150+
skills_dir = self.skills_dest(project_root).resolve()
151+
152+
for path in created:
153+
# Only touch SKILL.md files under the skills directory
154+
try:
155+
path.resolve().relative_to(skills_dir)
156+
except ValueError:
157+
continue
158+
if path.name != "SKILL.md":
159+
continue
160+
161+
content_bytes = path.read_bytes()
162+
content = content_bytes.decode("utf-8")
163+
164+
# Inject disable-model-invocation: true (Claude skills run only when invoked)
165+
updated = self._inject_disable_model_invocation(content)
166+
167+
# Inject argument-hint if available for this skill
168+
skill_dir_name = path.parent.name # e.g. "speckit-plan"
169+
stem = skill_dir_name
170+
if stem.startswith("speckit-"):
171+
stem = stem[len("speckit-"):]
172+
hint = ARGUMENT_HINTS.get(stem, "")
173+
if hint:
174+
updated = self.inject_argument_hint(updated, hint)
175+
176+
if updated != content:
177+
path.write_bytes(updated.encode("utf-8"))
178+
self.record_file_in_manifest(path, project_root, manifest)
179+
180+
return created

0 commit comments

Comments
 (0)