@codewalla_india/openspec 1.0.2 → 1.0.4

package/README.md

@@ -64,7 +64,9 @@ AI:  Created openspec/changes/add-dark-mode/
      Ready for implementation!
 
 You: /opsx:apply
-AI:  Implementing tasks...
+AI:  Comprehension check — 6 questions on your proposal, design, specs, and tasks...
+     ✓ 83% — ready to implement.
+     Implementing tasks...
      ✓ 1.1 Add theme context provider
      ✓ 1.2 Create toggle component
      ✓ 2.1 Add CSS variables
@@ -106,8 +108,9 @@ Now talk to your AI:
 
 - **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
 - **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
+- **Ready to implement?** Run `/opsx:apply` — a short comprehension quiz checks you understand the proposal, design, specs, and tasks before any code is written.
 
-Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
+The default `core` profile includes `/opsx:explore`, `/opsx:propose`, `/opsx:apply`, `/opsx:sync`, and `/opsx:archive`. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
 
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
@@ -182,6 +185,8 @@ openspec update
 
 **Context hygiene**: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.
 
+**Comprehension check**: `/opsx:apply` runs a short quiz (enabled by default) on proposal, design, specs, and pending tasks before implementation. Questions test holistic understanding of the change, not task numbers or checklist trivia. Disable with `comprehension.enabled: false` in `openspec/config.yaml`. See [Workflows](docs/workflows.md#comprehension-quiz-before-apply).
+
 ## Contributing
 
 **Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.

package/dist/commands/workflow/instructions.js

@@ -304,7 +304,7 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
             state = 'blocked';
             missingComprehension = true;
             comprehension = gate.info;
-            instruction = `Complete the comprehension quiz in /opsx:apply before implementation (score ≥ ${gate.info.thresholdPercent}% on specs and tasks).`;
+            instruction = `Complete the comprehension quiz in /opsx:apply before implementation (score ≥ ${gate.info.thresholdPercent}% on proposal, design, specs, and tasks).`;
         }
         else if (gate.active && gate.info) {
             comprehension = gate.info;

package/dist/core/templates/workflows/apply-change.js

@@ -1,6 +1,7 @@
 import { ATLASSIAN_ENRICHMENT_GUIDANCE, CONTEXT7_LOOKUP_GUIDANCE, PLAYWRIGHT_APPLY_GUARDRAIL, } from './mcp-guidance.js';
 import { COMPREHENSION_APPLY_GUARDRAIL, COMPREHENSION_QUIZ_GUIDANCE, } from './comprehension-guidance.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_SELECT_CHANGE } from './user-prompt-guidance.js';
 export function getApplyChangeSkillTemplate() {
     return {
         name: 'openspec-apply-change',
@@ -18,7 +19,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, ${PROMPT_SELECT_CHANGE}
 
    Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:apply <other>\`).
 
@@ -187,7 +188,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, ${PROMPT_SELECT_CHANGE}
 
    Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:apply <other>\`).
 

package/dist/core/templates/workflows/archive-change.js

@@ -1,4 +1,5 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_CONFIRM, PROMPT_SELECT_CHANGE } from './user-prompt-guidance.js';
 export function getArchiveChangeSkillTemplate() {
     return {
         name: 'openspec-archive-change',
@@ -13,7 +14,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.
+   ${PROMPT_SELECT_CHANGE}
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.
@@ -31,7 +32,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    **If any artifacts are not \`done\`:**
    - Display warning listing incomplete artifacts
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - ${PROMPT_CONFIRM}
    - Proceed if user confirms
 
 3. **Check task completion status**
@@ -42,7 +43,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    **If incomplete tasks found:**
    - Display warning showing count of incomplete tasks
-   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - ${PROMPT_CONFIRM}
    - Proceed if user confirms
 
    **If no tasks file exists:** Proceed without task-related warning.
@@ -130,7 +131,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.
+   ${PROMPT_SELECT_CHANGE}
 
    Show only active changes (not already archived).
    Include the schema used for each change if available.

package/dist/core/templates/workflows/bulk-archive-change.js

@@ -1,4 +1,5 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_CONFIRM, PROMPT_MULTI_SELECT_CHANGES } from './user-prompt-guidance.js';
 export function getBulkArchiveChangeSkillTemplate() {
     return {
         name: 'openspec-bulk-archive-change',
@@ -21,7 +22,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 2. **Prompt for change selection**
 
-   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   ${PROMPT_MULTI_SELECT_CHANGES}
    - 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)
@@ -102,7 +103,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 7. **Confirm batch operation**
 
-   Use **AskUserQuestion tool** with a single confirmation:
+   ${PROMPT_CONFIRM}
 
    - "Archive N changes?" with options based on status
    - Options might include:
@@ -269,7 +270,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 2. **Prompt for change selection**
 
-   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   ${PROMPT_MULTI_SELECT_CHANGES}
    - 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)
@@ -350,7 +351,7 @@ ${STORE_SELECTION_GUIDANCE}
 
 7. **Confirm batch operation**
 
-   Use **AskUserQuestion tool** with a single confirmation:
+   ${PROMPT_CONFIRM}
 
    - "Archive N changes?" with options based on status
    - Options might include:

package/dist/core/templates/workflows/comprehension-guidance.d.ts

@@ -4,6 +4,6 @@
  * Interpolated into apply skill and slash command templates so agents run
  * a spec comprehension gate before implementation.
  */
-export declare const COMPREHENSION_QUIZ_GUIDANCE = "4. **Comprehension quiz (required before implementation)**\n\n   After `openspec instructions apply --change \"<name>\" --json`, check comprehension status:\n\n   - If `missingComprehension` is true OR `comprehension.required && !comprehension.passed`:\n     - Do NOT edit application source code or mark task checkboxes yet\n     - Read `contextFiles.specs`, `contextFiles.tasks` (or the `tasks` array in apply JSON), and `contextFiles.design` (design for distractors only)\n     - Use `comprehension.questionCount` from the JSON as the number of questions\n\n   **Generate questions**\n   - Create exactly `comprehension.questionCount` multiple-choice questions\n   - Each question MUST map to one of:\n     - a `### Requirement:` or `#### Scenario:` from delta specs, OR\n     - a pending (unchecked) task from `tasks.md` / the apply `tasks` array\n   - When both specs and pending tasks exist, include at least 2 task-based questions and cover the rest from specs/scenarios\n   - Do NOT use completed tasks as question sources\n   - Each question: 4 options (1 correct from the source item, 3 plausible distractors from other requirements/scenarios/tasks in the change)\n\n   **Present and grade**\n   - Use the **AskUserQuestion tool** for each question (one at a time)\n   - Grade: `score_percent = round(correct / question_count * 100)`\n   - Pass when `score_percent >= comprehension.thresholdPercent` (default 80)\n\n   **On failure (score below threshold)**\n   - Announce score and that a new quiz is required\n   - Update `.comprehension-session.yaml` in the change dir with `used_sources` from this attempt\n   - Generate a NEW question set using different requirement/scenario/task sources (avoid `used_sources`)\n   - Retry until pass\n\n   **On pass**\n   ```bash\n   openspec instructions apply --change \"<name>\" --record-comprehension-pass --score <score> --attempt <n> --question-count <count> --json\n   ```\n   - Re-run `openspec instructions apply --change \"<name>\" --json`\n   - Confirm `state` is `\"ready\"` and `comprehension.passed` is true before continuing\n\n   **Output template**\n   ```\n   ## Applying: <change-name> \u2014 comprehension check\n\n   Specs: <requirementCount> requirements, <scenarioCount> scenarios; Tasks: <pendingTaskCount> pending \u2192 <questionCount> questions\n\n   Question 1/N: ...\n   ...\n   \u2713 Comprehension passed (<score>%, attempt <n>)\n   ```\n\n   Then continue to step 5 (show progress) and implementation.";
-export declare const COMPREHENSION_APPLY_GUARDRAIL = "- NEVER implement code or mark tasks while `missingComprehension` is true\n- NEVER skip the comprehension quiz when the apply JSON requires it\n- If the user asks to skip the quiz, refuse and explain they must pass or set comprehension.enabled: false in openspec/config.yaml";
+export declare const COMPREHENSION_QUIZ_GUIDANCE = "4. **Comprehension quiz (required before implementation)**\n\n   After `openspec instructions apply --change \"<name>\" --json`, check comprehension status:\n\n   - If `missingComprehension` is true OR `comprehension.required && !comprehension.passed`:\n     - Do NOT edit application source code or mark task checkboxes yet\n     - Read `contextFiles.proposal`, `contextFiles.design`, `contextFiles.specs`, and `contextFiles.tasks` (or the `tasks` array in apply JSON)\n     - Use `comprehension.questionCount` from the JSON as the number of questions\n\n   **Generate questions**\n   - Create exactly `comprehension.questionCount` multiple-choice questions\n   - Each question MUST map to one artifact category:\n     - **Proposal**: motivation, scope, or impact from `proposal.md`\n     - **Design**: decisions, trade-offs, or approach from `design.md`\n     - **Specs**: a `### Requirement:` or `#### Scenario:` from delta specs\n     - **Tasks**: conceptual understanding of the implementation plan from pending (unchecked) tasks\n   - When proposal, design, specs (with requirements), and pending tasks all exist, include at least one question from each category; fill remaining slots from any category\n   - Do NOT use completed tasks as question sources\n   - Each question: 4 options (1 correct from the source substance, 3 plausible distractors from other proposal/design/requirements/scenarios/task substance in the change)\n\n   **Task question quality**\n   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design\n   - **Forbidden**: task numbers, checklist order, \"which task says X verbatim\", or answers identifiable only by task index or checkbox position\n   - Good: \"What is the primary file where quiz rules are centralized?\" (answer from task substance)\n   - Bad: \"Which task number updates `comprehension-guidance.ts`?\" or \"What is the exact text of task 2.1?\"\n\n   **Present and grade**\n   - Present each question in chat with labeled options (A/B/C/D or 1\u20134)\n   - Ask ONE question at a time; after each, STOP and wait for the user's answer before the next question\n   - NEVER select answers yourself, infer what the user would pick, or call `--record-comprehension-pass` until the user has answered every question\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.\n   - Grade: `score_percent = round(correct / question_count * 100)`\n   - Pass when `score_percent >= comprehension.thresholdPercent` (default 80)\n\n   **On failure (score below threshold)**\n   - Announce score and that a new quiz is required\n   - Update `.comprehension-session.yaml` in the change dir with `used_sources` from this attempt\n   - Generate a NEW question set using different proposal/design/requirement/scenario/task sources (avoid `used_sources`)\n   - Retry until pass\n\n   **On pass**\n   ```bash\n   openspec instructions apply --change \"<name>\" --record-comprehension-pass --score <score> --attempt <n> --question-count <count> --json\n   ```\n   - Re-run `openspec instructions apply --change \"<name>\" --json`\n   - Confirm `state` is `\"ready\"` and `comprehension.passed` is true before continuing\n\n   **Output template**\n   ```\n   ## Applying: <change-name> \u2014 comprehension check\n\n   Proposal, design, specs (<requirementCount> requirements, <scenarioCount> scenarios), tasks (<pendingTaskCount> pending) \u2192 <questionCount> questions\n\n   Question 1/N: ...\n   ...\n   \u2713 Comprehension passed (<score>%, attempt <n>)\n   ```\n\n   Then continue to step 5 (show progress) and implementation.";
+export declare const COMPREHENSION_APPLY_GUARDRAIL = "- NEVER implement code or mark tasks while `missingComprehension` is true\n- NEVER skip the comprehension quiz when the apply JSON requires it\n- NEVER answer comprehension quiz questions yourself \u2014 the human developer must answer every question\n- NEVER call `--record-comprehension-pass` until the user has answered every question\n- If the user asks to skip the quiz, refuse and explain they must pass or set comprehension.enabled: false in openspec/config.yaml";
 //# sourceMappingURL=comprehension-guidance.d.ts.map

package/dist/core/templates/workflows/comprehension-guidance.js

@@ -4,33 +4,39 @@
  * Interpolated into apply skill and slash command templates so agents run
  * a spec comprehension gate before implementation.
  */
+import { COMPREHENSION_PRESENT_AND_GRADE } from './user-prompt-guidance.js';
 export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required before implementation)**
 
    After \`openspec instructions apply --change "<name>" --json\`, check comprehension status:
 
    - If \`missingComprehension\` is true OR \`comprehension.required && !comprehension.passed\`:
      - Do NOT edit application source code or mark task checkboxes yet
-     - Read \`contextFiles.specs\`, \`contextFiles.tasks\` (or the \`tasks\` array in apply JSON), and \`contextFiles.design\` (design for distractors only)
+     - Read \`contextFiles.proposal\`, \`contextFiles.design\`, \`contextFiles.specs\`, and \`contextFiles.tasks\` (or the \`tasks\` array in apply JSON)
      - Use \`comprehension.questionCount\` from the JSON as the number of questions
 
    **Generate questions**
    - Create exactly \`comprehension.questionCount\` multiple-choice questions
-   - Each question MUST map to one of:
-     - a \`### Requirement:\` or \`#### Scenario:\` from delta specs, OR
-     - a pending (unchecked) task from \`tasks.md\` / the apply \`tasks\` array
-   - When both specs and pending tasks exist, include at least 2 task-based questions and cover the rest from specs/scenarios
+   - Each question MUST map to one artifact category:
+     - **Proposal**: motivation, scope, or impact from \`proposal.md\`
+     - **Design**: decisions, trade-offs, or approach from \`design.md\`
+     - **Specs**: a \`### Requirement:\` or \`#### Scenario:\` from delta specs
+     - **Tasks**: conceptual understanding of the implementation plan from pending (unchecked) tasks
+   - When proposal, design, specs (with requirements), and pending tasks all exist, include at least one question from each category; fill remaining slots from any category
    - Do NOT use completed tasks as question sources
-   - Each question: 4 options (1 correct from the source item, 3 plausible distractors from other requirements/scenarios/tasks in the change)
+   - Each question: 4 options (1 correct from the source substance, 3 plausible distractors from other proposal/design/requirements/scenarios/task substance in the change)
 
-   **Present and grade**
-   - Use the **AskUserQuestion tool** for each question (one at a time)
-   - Grade: \`score_percent = round(correct / question_count * 100)\`
-   - Pass when \`score_percent >= comprehension.thresholdPercent\` (default 80)
+   **Task question quality**
+   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design
+   - **Forbidden**: task numbers, checklist order, "which task says X verbatim", or answers identifiable only by task index or checkbox position
+   - Good: "What is the primary file where quiz rules are centralized?" (answer from task substance)
+   - Bad: "Which task number updates \`comprehension-guidance.ts\`?" or "What is the exact text of task 2.1?"
+
+   ${COMPREHENSION_PRESENT_AND_GRADE}
 
    **On failure (score below threshold)**
    - Announce score and that a new quiz is required
    - Update \`.comprehension-session.yaml\` in the change dir with \`used_sources\` from this attempt
-   - Generate a NEW question set using different requirement/scenario/task sources (avoid \`used_sources\`)
+   - Generate a NEW question set using different proposal/design/requirement/scenario/task sources (avoid \`used_sources\`)
    - Retry until pass
 
    **On pass**
@@ -44,7 +50,7 @@ export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required be
    \`\`\`
    ## Applying: <change-name> — comprehension check
 
-   Specs: <requirementCount> requirements, <scenarioCount> scenarios; Tasks: <pendingTaskCount> pending → <questionCount> questions
+   Proposal, design, specs (<requirementCount> requirements, <scenarioCount> scenarios), tasks (<pendingTaskCount> pending) → <questionCount> questions
 
    Question 1/N: ...
    ...
@@ -54,5 +60,7 @@ export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required be
    Then continue to step 5 (show progress) and implementation.`;
 export const COMPREHENSION_APPLY_GUARDRAIL = `- NEVER implement code or mark tasks while \`missingComprehension\` is true
 - NEVER skip the comprehension quiz when the apply JSON requires it
+- NEVER answer comprehension quiz questions yourself — the human developer must answer every question
+- NEVER call \`--record-comprehension-pass\` until the user has answered every question
 - If the user asks to skip the quiz, refuse and explain they must pass or set comprehension.enabled: false in openspec/config.yaml`;
 //# sourceMappingURL=comprehension-guidance.js.map

package/dist/core/templates/workflows/continue-change.js

@@ -1,4 +1,5 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_SELECT_CHANGE_RECENT } from './user-prompt-guidance.js';
 export function getContinueChangeSkillTemplate() {
     return {
         name: 'openspec-continue-change',
@@ -13,7 +14,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.
+   ${PROMPT_SELECT_CHANGE_RECENT}
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name
@@ -134,7 +135,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.
+   ${PROMPT_SELECT_CHANGE_RECENT}
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name

package/dist/core/templates/workflows/ff-change.js

@@ -1,4 +1,5 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_CLARIFY, PROMPT_OPEN_ENDED } from './user-prompt-guidance.js';
 export function getFfChangeSkillTemplate() {
     return {
         name: 'openspec-ff-change',
@@ -13,7 +14,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:
+   ${PROMPT_OPEN_ENDED} Ask:
    > "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\`).
@@ -64,7 +65,7 @@ ${STORE_SELECTION_GUIDANCE}
       - Stop when all \`applyRequires\` artifacts are done
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - ${PROMPT_CLARIFY}
       - Then continue with creation
 
 5. **Show final status**
@@ -117,7 +118,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:
+   ${PROMPT_OPEN_ENDED} Ask:
    > "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\`).
@@ -168,7 +169,7 @@ ${STORE_SELECTION_GUIDANCE}
       - Stop when all \`applyRequires\` artifacts are done
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - ${PROMPT_CLARIFY}
       - Then continue with creation
 
 5. **Show final status**

package/dist/core/templates/workflows/new-change.js

@@ -1,4 +1,5 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_OPEN_ENDED } from './user-prompt-guidance.js';
 export function getNewChangeSkillTemplate() {
     return {
         name: 'openspec-new-change',
@@ -13,7 +14,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:
+   ${PROMPT_OPEN_ENDED} Ask:
    > "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 +90,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:
+   ${PROMPT_OPEN_ENDED} Ask:
    > "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\`).

package/dist/core/templates/workflows/propose.js

@@ -1,5 +1,6 @@
 import { ATLASSIAN_PROPOSE_GUIDANCE } from './mcp-guidance.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_CLARIFY, PROMPT_OPEN_ENDED } from './user-prompt-guidance.js';
 export function getOpsxProposeSkillTemplate() {
     return {
         name: 'openspec-propose',
@@ -25,7 +26,7 @@ ${ATLASSIAN_PROPOSE_GUIDANCE}
 
 1. **If no clear input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   ${PROMPT_OPEN_ENDED} Ask:
    > "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\`).
@@ -76,7 +77,7 @@ ${ATLASSIAN_PROPOSE_GUIDANCE}
       - Stop when all \`applyRequires\` artifacts are done
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - ${PROMPT_CLARIFY}
       - Then continue with creation
 
 5. **Show final status**
@@ -140,7 +141,7 @@ ${ATLASSIAN_PROPOSE_GUIDANCE}
 
 1. **If no input provided, ask what they want to build**
 
-   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   ${PROMPT_OPEN_ENDED} Ask:
    > "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\`).
@@ -191,7 +192,7 @@ ${ATLASSIAN_PROPOSE_GUIDANCE}
       - Stop when all \`applyRequires\` artifacts are done
 
    c. **If an artifact requires user input** (unclear context):
-      - Use **AskUserQuestion tool** to clarify
+      - ${PROMPT_CLARIFY}
       - Then continue with creation
 
 5. **Show final status**

package/dist/core/templates/workflows/sync-specs.js

@@ -1,4 +1,5 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_SELECT_CHANGE } from './user-prompt-guidance.js';
 export function getSyncSpecsSkillTemplate() {
     return {
         name: 'openspec-sync-specs',
@@ -15,7 +16,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.
+   ${PROMPT_SELECT_CHANGE}
 
    Show changes that have delta specs (under \`specs/\` directory).
 
@@ -162,7 +163,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.
+   ${PROMPT_SELECT_CHANGE}
 
    Show changes that have delta specs (under \`specs/\` directory).
 

package/dist/core/templates/workflows/user-prompt-guidance.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tool-agnostic user interaction guidance for agent workflows.
+ *
+ * Cursor's AskUserQuestion is an optional enhancement, not a requirement.
+ * All editors (Windsurf, Claude Code, etc.) use plain chat with stop-and-wait.
+ */
+export declare const PROMPT_SELECT_CHANGE = "Prompt the user to select a change:\n   - Run `openspec list --json` to get available changes\n   - Present the options clearly in chat (numbered or labeled)\n   - Ask ONE selection question; STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
+export declare const PROMPT_SELECT_CHANGE_RECENT = "Run `openspec list --json` to get available changes sorted by most recently modified. Then prompt the user to select which change to work on in chat. Ask ONE selection question; STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
+export declare const PROMPT_MULTI_SELECT_CHANGES = "Prompt the user to select one or more changes in chat:\n   - Show each change with its schema\n   - Allow multiple selections (e.g., \"select all that apply\" or comma-separated names)\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
+export declare const PROMPT_CONFIRM = "Ask the user to confirm before proceeding in chat:\n   - State what they are confirming and the consequences\n   - Present clear yes/no options\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
+export declare const PROMPT_OPEN_ENDED = "Ask the user an open-ended question in chat (no preset multiple-choice options):\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
+export declare const PROMPT_CLARIFY = "Ask the user a clarifying question in chat:\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
+export declare const COMPREHENSION_PRESENT_AND_GRADE = "**Present and grade**\n   - Present each question in chat with labeled options (A/B/C/D or 1\u20134)\n   - Ask ONE question at a time; after each, STOP and wait for the user's answer before the next question\n   - NEVER select answers yourself, infer what the user would pick, or call `--record-comprehension-pass` until the user has answered every question\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.\n   - Grade: `score_percent = round(correct / question_count * 100)`\n   - Pass when `score_percent >= comprehension.thresholdPercent` (default 80)";
+//# sourceMappingURL=user-prompt-guidance.d.ts.map

package/dist/core/templates/workflows/user-prompt-guidance.js

@@ -0,0 +1,39 @@
+/**
+ * Tool-agnostic user interaction guidance for agent workflows.
+ *
+ * Cursor's AskUserQuestion is an optional enhancement, not a requirement.
+ * All editors (Windsurf, Claude Code, etc.) use plain chat with stop-and-wait.
+ */
+const WAIT_FOR_USER = "STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.";
+const CURSOR_HINT = 'On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.';
+export const PROMPT_SELECT_CHANGE = `Prompt the user to select a change:
+   - Run \`openspec list --json\` to get available changes
+   - Present the options clearly in chat (numbered or labeled)
+   - Ask ONE selection question; ${WAIT_FOR_USER}
+   - ${CURSOR_HINT}`;
+export const PROMPT_SELECT_CHANGE_RECENT = `Run \`openspec list --json\` to get available changes sorted by most recently modified. Then prompt the user to select which change to work on in chat. Ask ONE selection question; ${WAIT_FOR_USER}
+   - ${CURSOR_HINT}`;
+export const PROMPT_MULTI_SELECT_CHANGES = `Prompt the user to select one or more changes in chat:
+   - Show each change with its schema
+   - Allow multiple selections (e.g., "select all that apply" or comma-separated names)
+   - ${WAIT_FOR_USER}
+   - ${CURSOR_HINT}`;
+export const PROMPT_CONFIRM = `Ask the user to confirm before proceeding in chat:
+   - State what they are confirming and the consequences
+   - Present clear yes/no options
+   - ${WAIT_FOR_USER}
+   - ${CURSOR_HINT}`;
+export const PROMPT_OPEN_ENDED = `Ask the user an open-ended question in chat (no preset multiple-choice options):
+   - ${WAIT_FOR_USER}
+   - ${CURSOR_HINT}`;
+export const PROMPT_CLARIFY = `Ask the user a clarifying question in chat:
+   - ${WAIT_FOR_USER}
+   - ${CURSOR_HINT}`;
+export const COMPREHENSION_PRESENT_AND_GRADE = `**Present and grade**
+   - Present each question in chat with labeled options (A/B/C/D or 1–4)
+   - Ask ONE question at a time; after each, STOP and wait for the user's answer before the next question
+   - NEVER select answers yourself, infer what the user would pick, or call \`--record-comprehension-pass\` until the user has answered every question
+   - ${CURSOR_HINT}
+   - Grade: \`score_percent = round(correct / question_count * 100)\`
+   - Pass when \`score_percent >= comprehension.thresholdPercent\` (default 80)`;
+//# sourceMappingURL=user-prompt-guidance.js.map

package/dist/core/templates/workflows/verify-change.js

@@ -1,5 +1,6 @@
 import { PLAYWRIGHT_VERIFY_GUIDANCE } from './mcp-guidance.js';
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_SELECT_CHANGE } from './user-prompt-guidance.js';
 export function getVerifyChangeSkillTemplate() {
     return {
         name: 'openspec-verify-change',
@@ -14,7 +15,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.
+   ${PROMPT_SELECT_CHANGE}
 
    Show changes that have implementation tasks (tasks artifact exists).
    Include the schema used for each change if available.
@@ -188,7 +189,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.
+   ${PROMPT_SELECT_CHANGE}
 
    Show changes that have implementation tasks (tasks artifact exists).
    Include the schema used for each change if available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codewalla_india/openspec",
-  "version": "1.0.02",
+  "version": "1.0.04",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",