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

.changeset/generic-ask-user-guidance.md

@@ -0,0 +1,5 @@
+---
+'@fission-ai/openspec': patch
+---
+
+Workflow skills and commands no longer tell agents to use the Claude Code-only AskUserQuestion tool. The same templates are generated for every supported tool, and agents without that tool (OpenCode, Factory Droid, Codex, and others) errored or stalled on the instruction. The guidance is now runtime-neutral: agents are simply told to ask the user.

skills/openspec-apply-change/SKILL.md

@@ -22,7 +22,7 @@ Implement tasks from an OpenSpec change.
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, run `openspec list --json` to get available changes and ask the user to select one
 
    Always announce: "Using change: <name>" and how to override (e.g., `/openspec-apply-change <other>`).
 

skills/openspec-archive-change/SKILL.md

@@ -19,7 +19,7 @@ Archive a completed change in the experimental workflow.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `openspec list --json` to get available changes. Ask the user to select one.
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.
@@ -64,7 +64,7 @@ Archive a completed change in the experimental workflow.
 
    **If any artifacts are neither `done` nor `skipped`** (skipped artifacts satisfy the requirement - the change declares skip_specs):
    - Display warning listing incomplete artifacts
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Ask the user to confirm they want to proceed
    - Proceed if user confirms
 
 3. **Check task completion status**
@@ -75,7 +75,7 @@ Archive a completed change in the experimental workflow.
 
    **If incomplete tasks found:**
    - Display warning showing count of incomplete tasks
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Ask the user to confirm they want to proceed
    - Proceed if user confirms
 
    **If no tasks file exists:** Proceed without task-related warning.

skills/openspec-bulk-archive-change/SKILL.md

@@ -27,7 +27,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
 2. **Prompt for change selection**
 
-   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   Ask the user to choose changes (multi-select):
    - Show each change with its schema
    - Include an option for "All changes"
    - Allow any number of selections (1+ works, 2+ is the typical use case)
@@ -137,7 +137,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
 7. **Confirm batch operation**
 
-   Use **AskUserQuestion tool** with a single confirmation:
+   Ask the user a single confirmation question:
 
    - "Archive N changes?" with options based on status
    - Options might include:

skills/openspec-continue-change/SKILL.md

@@ -19,7 +19,7 @@ Continue working on a change by creating the next artifact.
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then ask the user to select which change to work on.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name

skills/openspec-ff-change/SKILL.md

@@ -19,7 +19,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
 
 1. **If no clear input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
@@ -77,7 +77,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
       - Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - Ask the user to clarify
       - Then continue with creation
 
 5. **Show final status**

skills/openspec-new-change/SKILL.md

@@ -19,7 +19,7 @@ Start a new change using the experimental artifact-driven approach.
 
 1. **If no clear input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).

skills/openspec-propose/SKILL.md

@@ -29,7 +29,7 @@ When ready to implement, run /openspec-apply-change
 
 1. **If no clear input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
@@ -87,7 +87,7 @@ When ready to implement, run /openspec-apply-change
       - Stop when every artifact in the required set is `done`, `skipped`, or was deliberately skipped
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - Ask the user to clarify
       - Then continue with creation
 
 5. **Show final status**

skills/openspec-sync-specs/SKILL.md

@@ -21,7 +21,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `openspec list --json` to get available changes. Ask the user to select one.
 
    Show changes that have delta specs (under `specs/` directory).
 

skills/openspec-update-change/SKILL.md

@@ -19,7 +19,7 @@ Revise a change's existing planning artifacts and keep them coherent. Never edit
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then ask the user to select which change to update.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name

skills/openspec-verify-change/SKILL.md

@@ -19,7 +19,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
 1. **If no change name provided, prompt for selection**
 
-   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run `openspec list --json` to get available changes. Ask the user to select one.
 
    Show changes that have implementation tasks (tasks artifact exists).
    Include the schema used for each change if available.

src/core/templates/workflows/apply-change.ts

@@ -24,7 +24,7 @@ ${STORE_SELECTION_GUIDANCE}
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run \`openspec list --json\` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, run \`openspec list --json\` to get available changes and ask the user to select one
 
    Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:apply <other>\`).
 
@@ -209,7 +209,7 @@ ${STORE_SELECTION_GUIDANCE}
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run \`openspec list --json\` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, run \`openspec list --json\` to get available changes and ask the user to select one
 
    Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:apply <other>\`).
 

src/core/templates/workflows/archive-change.ts

@@ -21,7 +21,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run \`openspec list --json\` to get available changes. Ask the user to select one.
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.
@@ -66,7 +66,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    **If any artifacts are neither \`done\` nor \`skipped\`** (skipped artifacts satisfy the requirement - the change declares skip_specs):
    - Display warning listing incomplete artifacts
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Ask the user to confirm they want to proceed
    - Proceed if user confirms
 
 3. **Check task completion status**
@@ -77,7 +77,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    **If incomplete tasks found:**
    - Display warning showing count of incomplete tasks
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Ask the user to confirm they want to proceed
    - Proceed if user confirms
 
    **If no tasks file exists:** Proceed without task-related warning.
@@ -198,7 +198,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run \`openspec list --json\` to get available changes. Ask the user to select one.
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.

src/core/templates/workflows/bulk-archive-change.ts

@@ -29,7 +29,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 2. **Prompt for change selection**
 
-   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   Ask the user to choose changes (multi-select):
    - Show each change with its schema
    - Include an option for "All changes"
    - Allow any number of selections (1+ works, 2+ is the typical use case)
@@ -139,7 +139,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 7. **Confirm batch operation**
 
-   Use **AskUserQuestion tool** with a single confirmation:
+   Ask the user a single confirmation question:
 
    - "Archive N changes?" with options based on status
    - Options might include:
@@ -343,7 +343,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 2. **Prompt for change selection**
 
-   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   Ask the user to choose changes (multi-select):
    - Show each change with its schema
    - Include an option for "All changes"
    - Allow any number of selections (1+ works, 2+ is the typical use case)
@@ -454,7 +454,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 7. **Confirm batch operation**
 
-   Use **AskUserQuestion tool** with a single confirmation:
+   Ask the user a single confirmation question:
 
    - "Archive N changes?" with options based on status
    - Options might include:

src/core/templates/workflows/continue-change.ts

@@ -21,7 +21,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then ask the user to select which change to work on.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name
@@ -136,7 +136,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then ask the user to select which change to work on.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name

src/core/templates/workflows/ff-change.ts

@@ -21,7 +21,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no clear input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
@@ -79,7 +79,7 @@ ${STORE_SELECTION_GUIDANCE}
       - Stop when every artifact in the required set is \`done\`, \`skipped\`, or was deliberately skipped
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - Ask the user to clarify
       - Then continue with creation
 
 5. **Show final status**
@@ -134,7 +134,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
@@ -192,7 +192,7 @@ ${STORE_SELECTION_GUIDANCE}
       - Stop when every artifact in the required set is \`done\`, \`skipped\`, or was deliberately skipped
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - Ask the user to clarify
       - Then continue with creation
 
 5. **Show final status**

src/core/templates/workflows/new-change.ts

@@ -21,7 +21,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no clear input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
@@ -98,7 +98,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).

src/core/templates/workflows/propose.ts

@@ -31,7 +31,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no clear input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
@@ -89,7 +89,7 @@ ${STORE_SELECTION_GUIDANCE}
       - Stop when every artifact in the required set is \`done\`, \`skipped\`, or was deliberately skipped
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - Ask the user to clarify
       - Then continue with creation
 
 5. **Show final status**
@@ -154,7 +154,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   Ask the user (open-ended, no preset options):
    > "What change do you want to work on? Describe what you want to build or fix."
 
    From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
@@ -212,7 +212,7 @@ ${STORE_SELECTION_GUIDANCE}
       - Stop when every artifact in the required set is \`done\`, \`skipped\`, or was deliberately skipped
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - Ask the user to clarify
       - Then continue with creation
 
 5. **Show final status**

src/core/templates/workflows/sync-specs.ts

@@ -23,7 +23,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run \`openspec list --json\` to get available changes. Ask the user to select one.
 
    Show changes that have delta specs (under \`specs/\` directory).
 
@@ -230,7 +230,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run \`openspec list --json\` to get available changes. Ask the user to select one.
 
    Show changes that have delta specs (under \`specs/\` directory).
 

src/core/templates/workflows/update-change.ts

@@ -21,7 +21,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
+   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then ask the user to select which change to update.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name
@@ -108,7 +108,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to update.
+   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then ask the user to select which change to update.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name

src/core/templates/workflows/verify-change.ts

@@ -21,7 +21,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run \`openspec list --json\` to get available changes. Ask the user to select one.
 
    Show changes that have implementation tasks (tasks artifact exists).
    Include the schema used for each change if available.
@@ -193,7 +193,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Run \`openspec list --json\` to get available changes. Ask the user to select one.
 
    Show changes that have implementation tasks (tasks artifact exists).
    Include the schema used for each change if available.