feat: use Claude Code's native AskUserQuestion for /clarify and /checklist by 0xrafasec · Pull Request #2191 · github/spec-kit

0xrafasec · 2026-04-12T17:20:48Z

Summary

Replaces the Markdown-table question rendering in /clarify and /checklist with Claude Code's native AskUserQuestion structured picker, while preserving the original table behavior for all other agents.

Closes #2181

What changed

Templates: Added HTML-comment fence markers () around the question-rendering blocks in clarify.md and checklist.md. The markers are invisible to non-Claude agents — zero behavior change for them.
ClaudeIntegration: Extended setup() to post-process the fenced blocks at skill-generation time, following the same pattern used for argument-hint, user-invocable, and disable-model-invocation injection.
Schema mapping (documented inline):
- /clarify's Option | Description → AskUserQuestion's {label, description}
- /checklist's Option | Candidate | Why It Matters → {label: Candidate, description: Why It Matters}
Recommended option placed first in options[] with Recommended — <reasoning> prefix.
Free-form escape hatch preserved as a final synthetic option ("Provide my own short answer (≤5 words)").
All downstream behavior unchanged: question caps (5 for clarify, 3-initial/5-total for checklist), validation pass, incremental spec writes, Q1–Q5 labeling.

Files changed

File	Change
`templates/commands/clarify.md`	+2 lines (fence markers)
`templates/commands/checklist.md`	+2 lines (fence markers)
`src/specify_cli/integrations/claude/__init__.py`	+76 lines (post-processor + replacement blocks)
`tests/integrations/test_integration_claude.py`	+164 lines (9 new tests across 3 test classes)

Test results

28/28 Claude integration tests pass (19 existing + 9 new)
1246/1246 full test suite passes (18 skipped, unchanged from main)
Zero regressions

AI assistance disclosure

This PR was developed with assistance from Claude Code (Claude Opus 4.6). I reviewed, tested, and verified all changes manually. The implementation strategy follows the approach proposed in #2181 and matches the existing ClaudeIntegration post-processing patterns.

Test plan

All existing tests pass (uv run python -m pytest tests/ -q)
New tests verify Claude skills contain AskUserQuestion and not the original tables
New tests verify non-Claude integrations don't contain AskUserQuestion
New tests verify downstream behavior preservation (caps, validation, labeling)
New unit tests for replace_question_render_block() (no-fence passthrough, basic replacement)
Manual end-to-end verification: /speckit.clarify and /speckit.checklist inside Claude Code

🤖 Generated with Claude Code

Copilot

Pull request overview

This PR updates the /clarify and /checklist command templates to support Claude Code’s native AskUserQuestion structured picker by fencing the question-rendering blocks in the templates and post-processing them during Claude skill generation, while leaving non-Claude integrations functionally unchanged.

Changes:

Added HTML comment fence markers around question-rendering sections in clarify.md and checklist.md.
Extended ClaudeIntegration.setup() to replace fenced blocks with AskUserQuestion-based instructions for the Claude-generated skills.
Added Claude integration tests covering replacement behavior, parity expectations, and basic downstream behavior preservation checks.

Reviewed changes

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

File	Description
`templates/commands/clarify.md`	Adds begin/end fence markers around the clarify question-rendering rules block.
`templates/commands/checklist.md`	Adds begin/end fence markers around the checklist question-formatting rules block.
`src/specify_cli/integrations/claude/__init__.py`	Adds fenced-block replacement logic and AskUserQuestion replacement instructions for clarify/checklist at skill generation time.
`tests/integrations/test_integration_claude.py`	Adds tests ensuring Claude output uses AskUserQuestion, and that non-Claude outputs do not.

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

src/specify_cli/integrations/claude/__init__.py

templates/commands/clarify.md

templates/commands/checklist.md

tests/integrations/test_integration_claude.py

+            clarify_files = [
+                f for f in created
+                if "clarify" in f.name.lower() or "clarify" in str(f.parent).lower()
+            ]


tests/integrations/test_integration_claude.py

mnriem

Please deliver this as a preset similar to how it was done for VSCode (see https://github.com/github/spec-kit/tree/main/presets and foto see how it was done for VSCode see https://github.com/fdcastel/spec-kit-presets/tree/main/vscode-ask-questions)

Delivers the /speckit.clarify and /speckit.checklist AskUserQuestion integration as a stackable preset under presets/claude-ask-questions/ instead of modifying core templates or ClaudeIntegration. - presets/claude-ask-questions/preset.yml registers command overrides for speckit.clarify and speckit.checklist following the same pattern as the bundled lean preset. - Override commands replace the Markdown-table question-rendering blocks with AskUserQuestion instructions. Option | Description maps to {label, description} for clarify; Option | Candidate | Why It Matters maps to {label: Candidate, description: Why It Matters} for checklist. Recommended option is placed first with a "Recommended — <reasoning>" prefix; a final "Custom"/"Short" option preserves the free-form ≤5-word escape hatch. - Registered in presets/catalog.json as a bundled preset. Core templates, ClaudeIntegration, and the existing test suite are left untouched, so non-Claude agents and users who do not install this preset see no behavior change. Closes github#2181 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

0xrafasec · 2026-04-13T13:46:35Z

Thanks @mnriem for the thoughtful review and the pointer to the VSCode preset pattern — that's a much cleaner fit than modifying core.

I've reworked the PR from scratch as a preset: the in-core changes to ClaudeIntegration, the fence markers in templates/commands/clarify.md / checklist.md, and the added tests have all been dropped. The new implementation lives entirely under presets/claude-ask-questions/ and follows the same structure as the bundled lean preset:

presets/claude-ask-questions/preset.yml — registers speckit.clarify and speckit.checklist command overrides
presets/claude-ask-questions/commands/speckit.clarify.md — clarify command with AskUserQuestion replacing the Markdown-table rendering
presets/claude-ask-questions/commands/speckit.checklist.md — checklist command with AskUserQuestion replacing the Option | Candidate | Why It Matters table
presets/catalog.json — new bundled entry

Core templates, ClaudeIntegration, and the existing test suite are untouched, so users who don't install the preset see zero behavior change, and the Copilot comments on the previous implementation no longer apply. All 179 tests/test_presets.py tests pass locally.

Ready for another look when you have a moment. 🙏

mnriem · 2026-04-13T14:45:18Z

Looks good, but we also would like you to host this on a GitHub repository of your own. As per https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md

Per maintainer feedback on github#2191, presets should be hosted on the author's own GitHub repository and registered in catalog.community.json rather than bundled in spec-kit. Removes the bundled preset directory and its entry from the official catalog, and adds a community catalog entry pointing at the external repository and release archive. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR updates the preset catalog timestamps and adds a new community preset entry (claude-ask-questions) to presets/catalog.community.json.

Changes:

Bumped updated_at in presets/catalog.json.
Bumped updated_at in presets/catalog.community.json.
Added a new community preset entry: claude-ask-questions (v1.0.0).

Reviewed changes

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

File	Description
presets/catalog.json	Updates the catalog `updated_at` timestamp.
presets/catalog.community.json	Updates the catalog `updated_at` timestamp and adds the `claude-ask-questions` preset metadata entry.

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

presets/catalog.community.json

presets/catalog.json

…eset

0xrafasec · 2026-04-13T15:21:52Z

Thanks @mnriem — done.

The preset now lives in its own repository and is submitted through catalog.community.json per presets/PUBLISHING.md:

Repo: https://github.com/0xrafasec/spec-kit-preset-claude-ask-questions
Release: https://github.com/0xrafasec/spec-kit-preset-claude-ask-questions/releases/tag/v1.0.0
Archive URL (referenced from the catalog entry) returns 200 ✅

Changes in this PR (now scoped down to a single file):

Adds claude-ask-questions to presets/catalog.community.json, inserted alphabetically between canon-core and explicit-task-dependencies.
Bumps the community catalog updated_at to 2026-04-13.
The previously bundled presets/claude-ask-questions/ directory and its catalog.json entry have been removed — no core changes, no template changes, no test changes.

PUBLISHING.md checklist:

Valid preset.yml manifest (id lowercase-hyphen, semver, description < 200 chars, dot-notation command names)
README.md with description + usage
CONTRIBUTING.md
LICENSE (MIT)
CHANGELOG.md
Public GitHub repo + tagged v1.0.0 release
Alphabetical position in catalog.community.json
Tested locally with specify preset add --dev — command overrides register to .claude/commands/speckit.clarify.md and .claude/commands/speckit.checklist.md

Ready for another look whenever you have a moment 🙏

Copilot

Pull request overview

This PR updates the preset catalogs by adding a new community preset entry (claude-ask-questions) and bumping catalog timestamps, making the preset discoverable via the built-in community preset catalog.

Changes:

Add claude-ask-questions to presets/catalog.community.json.
Bump updated_at in both presets/catalog.community.json and presets/catalog.json.

Show a summary per file

File	Description
presets/catalog.json	Updates top-level `updated_at` timestamp.
presets/catalog.community.json	Updates top-level `updated_at` and adds the `claude-ask-questions` community preset entry.

Copilot's findings

Tip

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

Files reviewed: 2/2 changed files
Comments generated: 2

presets/catalog.json

 {
  "schema_version": "1.0",
-  "updated_at": "2026-04-10T00:00:00Z",
+  "updated_at": "2026-04-13T00:00:00Z",


presets/catalog.community.json

+    "claude-ask-questions": {
+      "name": "Claude AskUserQuestion",
+      "id": "claude-ask-questions",
+      "version": "1.0.0",
+      "description": "Upgrades /speckit.clarify and /speckit.checklist on Claude Code from Markdown-table prompts to the native AskUserQuestion picker, with a recommended option and reasoning on every question.",
+      "author": "0xrafasec",
+      "repository": "https://github.com/0xrafasec/spec-kit-preset-claude-ask-questions",
+      "download_url": "https://github.com/0xrafasec/spec-kit-preset-claude-ask-questions/archive/refs/tags/v1.0.0.zip",
+      "homepage": "https://github.com/0xrafasec/spec-kit-preset-claude-ask-questions",
+      "documentation": "https://github.com/0xrafasec/spec-kit-preset-claude-ask-questions/blob/main/README.md",
+      "license": "MIT",


mnriem

Please address Copilot feedback. Should be the latest thing I hope

0xrafasec requested a review from mnriem as a code owner April 12, 2026 17:20

Copilot AI review requested due to automatic review settings April 12, 2026 17:20

0xrafasec mentioned this pull request Apr 12, 2026

[Feature]: Use Claude Code's native AskUserQuestion tool instead of numbered-option prompts #2181

Open

11 tasks

Copilot started reviewing on behalf of 0xrafasec April 12, 2026 17:21 View session

Copilot AI reviewed Apr 12, 2026

View reviewed changes

mnriem requested changes Apr 13, 2026

View reviewed changes

0xrafasec force-pushed the feat/claude-ask-user-question branch from 9ddb174 to 64ea94d Compare April 13, 2026 13:46

Copilot AI review requested due to automatic review settings April 13, 2026 15:12

Copilot started reviewing on behalf of 0xrafasec April 13, 2026 15:13 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

presets/catalog.community.json Outdated Show resolved Hide resolved

presets/catalog.json Show resolved Hide resolved

docs(catalog): sync claude-ask-questions description with upstream pr…

0c06461

…eset

mnriem self-assigned this Apr 13, 2026

mnriem requested a review from Copilot April 13, 2026 16:00

Copilot started reviewing on behalf of mnriem April 13, 2026 16:01 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

mnriem self-requested a review April 13, 2026 16:19

mnriem requested changes Apr 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: use Claude Code's native AskUserQuestion for /clarify and /checklist#2191

feat: use Claude Code's native AskUserQuestion for /clarify and /checklist#2191
0xrafasec wants to merge 3 commits intogithub:mainfrom
0xrafasec:feat/claude-ask-user-question

0xrafasec commented Apr 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Uh oh!

0xrafasec commented Apr 13, 2026

Uh oh!

mnriem commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

0xrafasec commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

mnriem left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

0xrafasec commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Files changed

Test results

AI assistance disclosure

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

0xrafasec commented Apr 13, 2026

Uh oh!

mnriem commented Apr 13, 2026

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!

0xrafasec commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

0xrafasec commented Apr 12, 2026 •

edited

Loading