feat: add question-render fenced markers and Claude transformer

[Rohan-1920]

🚀 PR: Add Claude-native AskUserQuestion Rendering Pipeline

Overview

• Adds a non-invasive transformation layer for Claude Code integration in spec-kit
• Converts Markdown question tables into structured AskUserQuestion payloads
• Only applies to Claude integration — all other agents remain unchanged
• No changes to CLI behavior or core command logic

---

Changes

Templates

• Added fenced markers to isolate question-rendering blocks in:

  • templates/commands/clarify.md
  • templates/commands/checklist.md

• Markers used:

  • <!-- speckit:question-render:begin -->
  • <!-- speckit:question-render:end -->

• No changes to existing logic or structure

---

Core Module

New file: src/specify_cli/core/question_transformer.py

• Detects fenced question blocks

• Parses:

  • Option | Description (clarify)
  • Option | Candidate | Why It Matters (checklist)

• Converts into AskUserQuestion payload

• Extra behavior:

  • Recommended option prioritized (clarify)
  • Adds fallback option: “Provide my own short answer (≤10 words)”
  • Safe handling for duplicates
  • Returns original content unchanged when no markers exist

---

Claude Integration

• Updated src/specify_cli/integrations/claude/__init__.py
• Transformation applied only for Claude Code
• Other integrations remain byte-identical

---

Agents Fix

• Updated src/specify_cli/agents.py
• Fixed {SCRIPT} / {AGENT_SCRIPT} resolution logic
• Improved cross-platform compatibility

---

Tests

Unit Tests

• tests/test_question_transformer.py
  • 31 tests covering parsing, edge cases, and mapping logic

Integration Tests

• tests/integrations/test_integration_claude.py
  • 8 tests covering:
    • AskUserQuestion generation
    • clarify & checklist flows
    • no Markdown leakage in Claude output
    • non-Claude agents remain unchanged

---

Backward Compatibility

• Non-Claude agents are fully unaffected
• HTML comment markers are invisible to all other systems
• No CLI flags or config changes introduced
• No changes to existing command behavior

---

Result

• Before: Markdown table-based questions with manual selection
• After (Claude only): Native AskUserQuestion UI with structured selection and fallback option

[Copilot]

Pull request overview

Adds a Claude-specific post-processing layer that converts fenced “question table” blocks in generated SKILL.md files into structured JSON payloads intended for Claude’s native question UI, while also adjusting skill placeholder resolution logic for cross-platform script variants.

Changes:

• Added HTML comment fence markers around question tables in clarify.md and checklist.md templates.
• Introduced src/specify_cli/core/question_transformer.py to detect fenced blocks, parse markdown tables, and emit a JSON payload block.
• Updated Claude integration setup to run the transformer during skill installation; updated {SCRIPT} / {AGENT_SCRIPT} placeholder resolution fallback logic.

Show a summary per file

File	Description
tests/test_question_transformer.py	New unit tests for table parsing and fenced-block transformation behavior
tests/integrations/test_integration_claude.py	New integration tests asserting Claude skills contain transformed JSON and no raw markers
templates/commands/clarify.md	Adds begin/end markers around the clarify question table example
templates/commands/checklist.md	Adds begin/end markers around the checklist question table example
src/specify_cli/integrations/claude/init.py	Runs question block transformation when generating Claude SKILL.md files
src/specify_cli/core/question_transformer.py	New transformer/parser implementation for fenced question blocks
src/specify_cli/core/init.py	Adds core package initializer
src/specify_cli/agents.py	Updates script variant fallback selection for {SCRIPT} / {AGENT_SCRIPT} placeholders

Copilot's findings

Tip

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

Comments suppressed due to low confidence (2)

src/specify_cli/agents.py:366

• fallback_order is only built when init_opts['script'] is not in {"sh","ps"}. If the user explicitly sets script: ps (or sh) but that variant is missing from scripts or agent_scripts, both {SCRIPT} / {AGENT_SCRIPT} can fail to resolve because the later fallback loop has an empty fallback_order. Build a fallback list whenever the chosen variant isn’t available (or always include the other available variants), so placeholder resolution works even with a mismatched/partial set of script variants.

        script_variant = init_opts.get("script")
        fallback_order: list[str] = []
        if script_variant not in {"sh", "ps"}:
            # Build fallback order: prefer the variant present in BOTH scripts and
            # agent_scripts so that {SCRIPT} and {AGENT_SCRIPT} resolve consistently.
            # On Windows the OS default is "ps", but if only "sh" is available in
            # agent_scripts we must still resolve both placeholders from "sh".
            default_variant = "ps" if platform.system().lower().startswith("win") else "sh"
            secondary_variant = "sh" if default_variant == "ps" else "ps"

            # Prefer a variant that satisfies both scripts AND agent_scripts.
            both_variants = set(scripts) & set(agent_scripts)
            if both_variants:
                for v in (default_variant, secondary_variant):
                    if v in both_variants:
                        fallback_order.append(v)
                for v in sorted(both_variants):
                    if v not in fallback_order:
                        fallback_order.append(v)

            # Then add remaining variants from scripts / agent_scripts.
            for v in (default_variant, secondary_variant):
                if v not in fallback_order and (v in scripts or v in agent_scripts):
                    fallback_order.append(v)
            for key in list(scripts) + list(agent_scripts):
                if key not in fallback_order:
                    fallback_order.append(key)

            script_variant = fallback_order[0] if fallback_order else None

        # Resolve script_command: try script_variant first, then walk fallback_order.
        # This ensures sh-only extensions work on Windows (where default is "ps").
        script_command = scripts.get(script_variant) if script_variant else None
        if not script_command:
            for _variant in fallback_order:
                candidate = scripts.get(_variant)
                if candidate:
                    script_command = candidate
                    break
        if script_command:
            script_command = script_command.replace("{ARGS}", "$ARGUMENTS")
            body = body.replace("{SCRIPT}", script_command)

        # Resolve agent_script_command: same cross-platform fallback.
        agent_script_command = agent_scripts.get(script_variant) if script_variant else None
        if not agent_script_command:
            for _variant in fallback_order:
                candidate = agent_scripts.get(_variant)
                if candidate:
                    agent_script_command = candidate
                    break
        if agent_script_command:
            agent_script_command = agent_script_command.replace("{ARGS}", "$ARGUMENTS")
            body = body.replace("{AGENT_SCRIPT}", agent_script_command)

src/specify_cli/core/question_transformer.py:135

• Checklist vs clarify detection uses a simple substring check for | Candidate | inside the fenced block. This can mis-detect if the word “Candidate” appears in a clarify table description, and it’s sensitive to header capitalization/spacing. Consider detecting schema from the parsed header cell count/names (e.g., first non-empty table row) rather than a raw substring search.

    def _replace(match: re.Match) -> str:
        block = match.group(1)
        is_checklist = "| Candidate |" in block or "|Candidate|" in block
        options = parse_checklist(block) if is_checklist else parse_clarify(block)
        return _build_payload(options)

• Files reviewed: 8/8 changed files
• Comments generated: 7

[mnriem]

Please deliver this as a community preset. See https://github.com/github/spec-kit/blob/main/presets/README.md?tab=readme-ov-file#presets--customize-existing-workflows

[Rohan-1920]

Nice work on this feature 👏

• The fenced marker implementation looks clean and readable.
• Claude transformer integration is well-structured.
• Good to see test coverage included for the transformer logic.

Minor suggestion:

• Consider adding a brief docstring or comment explaining the regex (FENCE_RE) for future readability.

Overall, solid implementation 👍

[mnriem]

Please deliver this as an extension

[Rohan-1920]

Please deliver this as an extension

Thanks for the feedback!

Got it I’ll refactor this into an extension instead of integrating it directly into the core.

I’ll update the PR once that’s done.

[Rohan-1920]

Please deliver this as an extension

Hi I’ve implemented the extension-based skill renderer refactor (registry + RendererExtension, question-render + Claude transforms in separate modules) and pushed it to feat/question-render-transformer on fork:

https://github.com/Rohan-1920/spec-kit/tree/feat/question-render-transformer

While rebasing I also restored a broken agents.py from main and added set_frontmatter_key so disable-model-invocation:
false applies correctly when preset/build_skill_frontmatter already sets true.

Happy to open a PR against this repo if you want let me know the preferred base branch.