fix(templates): replace Claude-only AskUserQuestion instruction with neutral ask-the-user guidance by clay-good · Pull Request #1464 · Fission-AI/OpenSpec

clay-good · 2026-07-27T22:31:52Z

Closes #920
Closes #717

Status

Ready. Full suite green (2,279 tests), parity/vocabulary/completion meta-tests pass, e2e verified across all supported tools, three independent adversarial reviews found no defects.

What was wrong

Every workflow skill/command template told agents to "Use the AskUserQuestion tool" — a tool that only exists in Claude Code. The same templates generate assets for every supported tool, so:

OpenCode (Skills assume Claude Code tool API when using with OpenCode #920, P0-critical): its question tool is named question; agents tried to call a tool that doesn't exist.
Factory Droid ([Bug] Invoking /opsx-new in Factory Droid returns error #717): its native AskUser parser choked on the instruction with Error: Invalid AskUser questionnaire format at line 1.
Codex and other tools stalled or attempted unavailable tools (Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools #1103's residual complaint — its TodoWrite/Task items were already fixed by fix(templates): replace Claude-only TodoWrite instruction with a generic todo list #1403).

28 references across 10 workflow templates, plus the 15 mirrored lines in the committed skills/*/SKILL.md files that npx skills add Fission-AI/OpenSpec installs verbatim.

How it was fixed

Same shape as the merged TodoWrite fix (#1403): the instruction is now runtime-neutral. Every interaction constraint the old text encoded survives:

Before	After
Use the AskUserQuestion tool (open-ended, no preset options) to ask:	Ask the user (open-ended, no preset options):
Use the AskUserQuestion tool to let the user select.	Ask the user to select one.
Use AskUserQuestion tool with multi-select to let user choose changes:	Ask the user to choose changes (multi-select):
Use AskUserQuestion tool with a single confirmation:	Ask the user a single confirmation question:
Use AskUserQuestion tool to confirm user wants to proceed	Ask the user to confirm they want to proceed
Use AskUserQuestion tool to clarify	Ask the user to clarify

Claude Code still surfaces its native question UI from the neutral phrasing (same accepted tradeoff as #1403). skills/*/SKILL.md regenerated via pnpm generate:skills; golden hashes via pnpm regen:parity-hashes; patch changeset included, so existing users pick up the new text through the normal openspec update full-file rewrite.

Proof

openspec init --tools all on this branch: 0 occurrences of AskUserQuestion / TodoWrite / Task tool / subagent_type in any generated asset (all three tool-name complaints in Skills assume Claude Code tool API when using with OpenCode #920 now resolved); the neutral phrasing appears in 124 generated files, including .opencode/ and .factory/.
On main, the same grep finds the reference in every workflow command/skill generated for every tool.
vitest run: 112 files, 2,279 tests pass, including skill-templates-parity, skillssh-parity (regenerates SKILL.md from source and diffs), vocabulary sweep, and completion registry.
Three adversarial reviews (semantic completeness, CI/conventions, back-compat): no findings. Notably, nothing in src/ parses the old string — the Factory adapter passes template text through untouched, which is exactly why the fix belongs at the template layer.

Notes

Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools #1103 (Codex) is deliberately not closed here: it's owned by open PR fix(codex): rewrite unsupported tool references #1133, which rewrites tool references at the Codex adapter layer. This PR fixes the template layer for all tools; I'll cross-link on the issue.
Text-only change: no CLI flags, no APIs, no schema, no behavior change for any existing command.

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Updated workflow guidance to use tool-neutral prompts when requesting user input.
- Clarified change selection by directing workflows to list available changes before asking the user to choose.
- Standardized confirmation and clarification instructions across OpenSpec workflows.
Tests
- Updated template parity expectations to reflect the revised workflow guidance.

…neutral ask-the-user guidance The workflow skill/command templates told agents to use the AskUserQuestion tool, which only exists in Claude Code. The same templates generate skills and commands for every supported tool, so OpenCode (whose tool is named question), Factory Droid (whose native AskUser parser errors on the instruction), Codex, and the rest were instructed to use a tool they don't have. The guidance is now runtime-neutral, matching the TodoWrite fix in #1403. Fixes #920 Fixes #717 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

coderabbitai · 2026-07-27T22:32:12Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 99755a1e-65e7-43a2-a849-0d4c69e7dbcc

📥 Commits

Reviewing files that changed from the base of the PR and between ebf66c7 and 531ead7.

📒 Files selected for processing (22)

.changeset/generic-ask-user-guidance.md
skills/openspec-apply-change/SKILL.md
skills/openspec-archive-change/SKILL.md
skills/openspec-bulk-archive-change/SKILL.md
skills/openspec-continue-change/SKILL.md
skills/openspec-ff-change/SKILL.md
skills/openspec-new-change/SKILL.md
skills/openspec-propose/SKILL.md
skills/openspec-sync-specs/SKILL.md
skills/openspec-update-change/SKILL.md
skills/openspec-verify-change/SKILL.md
src/core/templates/workflows/apply-change.ts
src/core/templates/workflows/archive-change.ts
src/core/templates/workflows/bulk-archive-change.ts
src/core/templates/workflows/continue-change.ts
src/core/templates/workflows/ff-change.ts
src/core/templates/workflows/new-change.ts
src/core/templates/workflows/propose.ts
src/core/templates/workflows/sync-specs.ts
src/core/templates/workflows/update-change.ts
src/core/templates/workflows/verify-change.ts
test/core/templates/skill-templates-parity.test.ts

📝 Walkthrough

Walkthrough

Workflow templates and generated skills replace explicit AskUserQuestion references with runtime-neutral instructions for user selection, clarification, and confirmation. Template parity hashes and the release changeset are updated accordingly.

Changes

Tool-neutral user guidance

Layer / File(s)	Summary
Workflow template prompt updates `src/core/templates/workflows/*`	Standard and OPSX workflow templates update interactive selection, clarification, and confirmation instructions.
Generated skill prompt updates `skills/openspec-*/SKILL.md`	Checked-in skill guidance mirrors the runtime-neutral user-interaction wording.
Parity and release metadata `test/core/templates/skill-templates-parity.test.ts`, `.changeset/generic-ask-user-guidance.md`	Golden template and generated-skill hashes are refreshed, and the changeset records the guidance update.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

Fission-AI/OpenSpec#450: Introduced the sync workflow whose selection guidance is updated here.
Fission-AI/OpenSpec#451: Added archive workflow prompting that these changes make tool-neutral.
Fission-AI/OpenSpec#527: Added bulk-archive prompting updated by this change.

Suggested reviewers: alfred-openspec, tabishb

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	Issue [`#717`] is addressed, but [`#920`] is incomplete because TodoWrite and Task API mismatches in affected skills were not changed.	Update the affected skills/templates to also replace TodoWrite and Task with the correct OpenCode equivalents, then verify the workflows again.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: replacing Claude-only AskUserQuestion guidance with neutral ask-the-user wording.
Out of Scope Changes check	✅ Passed	The diff stays focused on prompt wording, regenerated skills, parity hashes, and the changeset, with no unrelated behavior changes visible.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/generic-ask-user-guidance

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

cloudflare-workers-and-pages · 2026-07-27T22:42:39Z

Deploying openspec-docs with Cloudflare Pages

Latest commit:	`ee8f706`
Status:	✅ Deploy successful!
Preview URL:	https://ee3cdd2a.openspec-docs.pages.dev
Branch Preview URL:	https://fix-generic-ask-user-guidanc.openspec-docs.pages.dev

View logs

alfred-openspec

Reviewed at 16bf214. The neutral phrasing preserves selection, multi-select, confirmation, and clarification semantics; 19 parity/vocabulary tests, build, lint, generation for every supported tool with zero forbidden tool references, the 2,279-test cross-platform suite, and all CI/security checks pass.

clay-good requested a review from a team as a code owner July 27, 2026 22:31

clay-good requested review from alfred-openspec and removed request for a team July 27, 2026 22:31

clay-good mentioned this pull request Jul 27, 2026

Codex generated assets reference unsupported AskUserQuestion/TodoWrite/Task tools #1103

Open

Merge branch 'main' into fix/generic-ask-user-guidance

ee8f706

Merge branch 'main' into fix/generic-ask-user-guidance

16bf214

alfred-openspec approved these changes Jul 27, 2026

View reviewed changes

clay-good added this pull request to the merge queue Jul 27, 2026

Merged via the queue into main with commit 5bcf057 Jul 27, 2026
16 checks passed

clay-good deleted the fix/generic-ask-user-guidance branch July 27, 2026 23:07

openspec-release-bot Bot mentioned this pull request Jul 27, 2026

chore(release): version packages #1380

Merged

clay-good mentioned this pull request Jul 27, 2026

fix(cli): resolve store pointer for view command #1455

Merged

coderabbitai Bot mentioned this pull request Jul 28, 2026

fix(templates): auto-select the only active change instead of always prompting #1468

Merged

This was referenced Jul 28, 2026

feat: add Kimi CLI as a supported AI tool #640

Closed

fix(codex): rewrite unsupported tool references #1133

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(templates): replace Claude-only AskUserQuestion instruction with neutral ask-the-user guidance - #1464

fix(templates): replace Claude-only AskUserQuestion instruction with neutral ask-the-user guidance#1464
clay-good merged 3 commits into
mainfrom
fix/generic-ask-user-guidance

clay-good commented Jul 27, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 27, 2026 •

edited

Loading

Walkthrough

Changes

❌ Failed checks (2 warnings)

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 27, 2026 •

edited

Loading

Uh oh!

alfred-openspec left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

clay-good commented Jul 27, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Status

What was wrong

How it was fixed

Proof

Notes

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

❌ Failed checks (2 warnings)

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying openspec-docs with Cloudflare Pages

Uh oh!

alfred-openspec left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clay-good commented Jul 27, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 27, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 27, 2026 •

edited

Loading