feat: add argument-hint frontmatter to Claude Code commands (#1951) by Quratulain-bilal · Pull Request #2059 · github/spec-kit

Quratulain-bilal · 2026-04-02T10:35:50Z

Summary

Add argument-hint frontmatter injection to Claude Code skills (SkillsIntegration)
ClaudeIntegration.setup() delegates to super().setup() then post-processes each
SKILL.md to inject hints
No duplication of base class logic — clean post-processing approach (addresses previous
Copilot feedback)
Proper \r\n / \n EOL preservation in inject_argument_hint()

Command	argument-hint
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

What changed after #2051 merge

Rebased on SkillsIntegration base class (replaces old MarkdownIntegration)
Skills now live at .claude/skills/speckit-*/SKILL.md
Removed release script changes (scripts deleted in Stage 6 migration)
All previous Copilot review feedback addressed

Closes #1951

Test plan

6 argument-hint tests in tests/integrations/test_integration_claude.py
All existing Claude integration tests pass
uv run pytest tests/integrations/test_integration_claude.py -q

) 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 <noreply@anthropic.com>

Copilot

Pull request overview

Adds Claude Code–specific argument-hint frontmatter to generated /speckit.* command files at release-package generation time, improving the Claude slash-command UX without making the shared templates agent-specific.

Changes:

Inject argument-hint into generated Claude command frontmatter based on command name.
Keep templates agent-agnostic by performing injection inside generate_commands() only when agent == claude.
Mirror the same behavior in both Bash and PowerShell release packaging scripts for parity.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
.github/workflows/scripts/create-release-packages.sh	Adds Claude-only `argument-hint` injection during command generation in release packaging.
.github/workflows/scripts/create-release-packages.ps1	Implements the same Claude-only `argument-hint` injection for PowerShell-based packaging parity.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

.github/workflows/scripts/create-release-packages.sh

.github/workflows/scripts/create-release-packages.ps1

mnriem

Please address Copilot feedback. Note that until we have fully migrated you will also have to addresss this in src/specify_cli/integrations/claude/init.py

Please add tests for this in tests/integrations/test_integration_claude.py

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 <noreply@anthropic.com>

- 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 <noreply@anthropic.com>

Quratulain-bilal · 2026-04-02T13:53:35Z

Done added argument-hint injection to src/specify_cli/integrations/claude/init.py with
inject_argument_hint() scoped to frontmatter only, and added 5 tests in
tests/integrations/test_integration_claude.py covering hint presence, correct values,
frontmatter scoping, ordering, and body-safety. See commit ffa6946.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/integrations/claude/__init__.py

tests/integrations/test_integration_claude.py

mnriem

Please address Copilot feedback. If not applicable, please explain why

- 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 <noreply@anthropic.com>

Quratulain-bilal · 2026-04-02T14:08:17Z

All 4 Copilot comments addressed in commit 6e5ba27:

Removed unused import re
inject_argument_hint() now pre-scans frontmatter and skips injection if argument-hint:
already exists prevents duplicates
Regarding scope: argument-hint is intentionally injected in both the release scripts and
integration setup the maintainer requested coverage in integrations/claude/init.py as
well, so both specify init --ai claude and release ZIPs get hints. Updated PR description
would be: hints are injected wherever Claude commands are generated.
test_hint_appears_after_description now asserts found_description flag so it fails
explicitly if no description: line is found. Also added
test_inject_argument_hint_skips_if_already_present for the duplicate-guard.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/integrations/claude/__init__.py

- 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 <noreply@anthropic.com>

mnriem · 2026-04-02T14:20:30Z

Can you hold of until PR #2051 gets merged and see if yours is still needed?

Quratulain-bilal · 2026-04-02T14:28:30Z

Sure, will hold off. Watching #2051 if it covers argument-hint injection for Claude
commands across all paths (release scripts + integration system), I'll close this PR.
Otherwise I'll rebase and fill any gaps.

Quratulain-bilal · 2026-04-02T17:14:35Z

#2051 is now merged. I've rebased/merged main into this branch and updated the
implementation to work with the new SkillsIntegration base class and .claude/skills/
layout. The argument-hint feature is still needed #2051 doesn't include it. Ready for
review.

Resolve conflicts with Stage 6 migration (github#2063) and release 0.4.5 (github#2064). Keep inject_argument_hint alongside new _render_skill and _build_skill_fm methods. Accept deletion of legacy release packaging scripts.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (2)

src/specify_cli/integrations/claude/init.py:149

The post-processing rewrites SKILL.md after super().setup() has already recorded file hashes in the integration manifest. Because the file content changes, the manifest will contain stale hashes and uninstall/modified-file detection may treat these files as user-modified. After writing updated content, re-record the file in the manifest (e.g., manifest.record_existing(rel_path) or the existing helper used elsewhere).

            content = path.read_text(encoding="utf-8")
            updated = self.inject_argument_hint(content, hint)
            if updated != content:
                path.write_text(updated, encoding="utf-8")

src/specify_cli/integrations/claude/init.py:112

After switching to super().setup(), the _render_skill() / _build_skill_fm() helpers appear unused (no call sites in the repo). Keeping them (and the yaml dependency) increases maintenance burden and can confuse future readers about which codepath is active. Consider removing them if they’re no longer part of the integration’s intended behavior.

    def _render_skill(self, template_name: str, frontmatter: dict[str, Any], body: str) -> str:
        """Render a processed command template as a Claude skill."""
        skill_name = f"speckit-{template_name.replace('.', '-')}"
        description = frontmatter.get(
            "description",
            f"Spec-kit workflow command: {template_name}",
        )
        skill_frontmatter = self._build_skill_fm(
            skill_name, description, f"templates/commands/{template_name}.md"
        )
        frontmatter_text = yaml.safe_dump(skill_frontmatter, sort_keys=False).strip()
        return f"---\n{frontmatter_text}\n---\n\n{body.strip()}\n"

    def _build_skill_fm(self, name: str, description: str, source: str) -> dict:
        from specify_cli.agents import CommandRegistrar
        return CommandRegistrar.build_skill_frontmatter(
            self.key, name, description, source
        )

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/integrations/claude/__init__.py

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.

Quratulain-bilal · 2026-04-02T19:54:12Z

Not applicable. super().setup() delegates to SkillsIntegration.setup() which calls
_build_skill_fm() → CommandRegistrar.build_skill_frontmatter(). That method already adds
disable-model-invocation: true for Claude (see agents.py line 398-400). The post-processing
step only injects argument-hint it does not touch or remove any existing frontmatter keys.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/integrations/claude/__init__.py

mnriem

Please address Copilot feedback. Make sure the hashes are recorded at the right time as that will make uninstall possible

- 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

Quratulain-bilal · 2026-04-02T20:17:13Z

Addressed all Copilot feedback in fa2fa9c:

Re-record manifest hash after argument-hint injection via record_file_in_manifest() so
check_modified()/uninstall stays in sync
Double-quote argument-hint values to match existing SKILL.md frontmatter style
read_bytes()/write_bytes() already applied in previous commit for platform-stable EOL

Regarding disable-model-invocation: not applicable super().setup() delegates to
SkillsIntegration.setup() which uses CommandRegistrar.build_skill_frontmatter(), and that already adds
disable-model-invocation: true for Claude (agents.py line 398-400).

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

mnriem

Almost there. Looks like there is a test failure

Quratulain-bilal requested a review from mnriem as a code owner April 2, 2026 10:35

mnriem requested a review from Copilot April 2, 2026 12:53

Copilot started reviewing on behalf of mnriem April 2, 2026 12:53 View session

Copilot AI approved these changes Apr 2, 2026

View reviewed changes

.github/workflows/scripts/create-release-packages.sh Outdated Show resolved Hide resolved

.github/workflows/scripts/create-release-packages.ps1 Outdated Show resolved Hide resolved

mnriem requested changes Apr 2, 2026

View reviewed changes

Quratulain-bilal and others added 2 commits April 2, 2026 18:46

mnriem requested a review from Copilot April 2, 2026 13:57

Copilot started reviewing on behalf of mnriem April 2, 2026 13:58 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

mnriem self-requested a review April 2, 2026 14:03

mnriem requested changes Apr 2, 2026

View reviewed changes

mnriem requested a review from Copilot April 2, 2026 14:09

Copilot started reviewing on behalf of mnriem April 2, 2026 14:09 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

src/specify_cli/integrations/claude/__init__.py Outdated Show resolved Hide resolved

src/specify_cli/integrations/claude/__init__.py Outdated Show resolved Hide resolved

src/specify_cli/integrations/claude/__init__.py Outdated Show resolved Hide resolved

mnriem self-requested a review April 2, 2026 14:19

Merge origin/main into feat/argument-hint-claude-commands

2e56a96

Merge origin/main into feat/argument-hint-claude-commands

9ab30ca

Resolve conflicts with Stage 6 migration (github#2063) and release 0.4.5 (github#2064). Keep inject_argument_hint alongside new _render_skill and _build_skill_fm methods. Accept deletion of legacy release packaging scripts.

mnriem requested a review from Copilot April 2, 2026 18:56

Copilot started reviewing on behalf of mnriem April 2, 2026 18:57 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

src/specify_cli/integrations/claude/__init__.py Show resolved Hide resolved

src/specify_cli/integrations/claude/__init__.py Outdated Show resolved Hide resolved

src/specify_cli/integrations/claude/__init__.py Show resolved Hide resolved

fix: use read_bytes/write_bytes for platform-stable EOL handling

c9d025c

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.

mnriem requested a review from Copilot April 2, 2026 20:04

Copilot started reviewing on behalf of mnriem April 2, 2026 20:05 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

src/specify_cli/integrations/claude/__init__.py Show resolved Hide resolved

src/specify_cli/integrations/claude/__init__.py Show resolved Hide resolved

mnriem requested changes Apr 2, 2026

View reviewed changes

mnriem requested a review from Copilot April 2, 2026 20:21

Copilot started reviewing on behalf of mnriem April 2, 2026 20:22 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

mnriem self-requested a review April 2, 2026 20:36

mnriem requested changes Apr 2, 2026

View reviewed changes

Conversation

Quratulain-bilal commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed after #2051 merge

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Quratulain-bilal commented Apr 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Quratulain-bilal commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem commented Apr 2, 2026

Uh oh!

Quratulain-bilal commented Apr 2, 2026

Uh oh!

Quratulain-bilal commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Quratulain-bilal commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Quratulain-bilal commented Apr 2, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Quratulain-bilal commented Apr 2, 2026 •

edited

Loading

Quratulain-bilal commented Apr 2, 2026 •

edited

Loading

Quratulain-bilal commented Apr 2, 2026 •

edited

Loading

Quratulain-bilal commented Apr 2, 2026 •

edited

Loading