@codewalla_india/openspec 1.0.3 → 1.0.5

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

@@ -15,6 +15,22 @@ import { readRegistrySnapshot } from '../../core/store/registry.js';
 import { readProjectConfig } from '../../core/project-config.js';
 import { checkComprehensionGate, ComprehensionPassError, recordComprehensionPass, } from '../../core/comprehension/index.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
+function buildArtifactPresence(contextFiles, pendingTaskCount) {
+    return {
+        hasPlan: (contextFiles.plan?.length ?? 0) > 0,
+        hasProposal: (contextFiles.proposal?.length ?? 0) > 0,
+        hasDesign: (contextFiles.design?.length ?? 0) > 0,
+        hasSpecs: (contextFiles.specs?.length ?? 0) > 0,
+        hasTasks: pendingTaskCount > 0 || (contextFiles.tasks?.length ?? 0) > 0,
+    };
+}
+function resolvePlanPath(contextFiles, changeDir) {
+    if (contextFiles.plan?.[0]) {
+        return contextFiles.plan[0];
+    }
+    const fallback = path.join(changeDir, 'plan.md');
+    return fs.existsSync(fallback) ? fallback : null;
+}
 // -----------------------------------------------------------------------------
 // Artifact Instructions Command
 // -----------------------------------------------------------------------------
@@ -298,13 +314,15 @@ export async function generateApplyInstructions(projectRoot, changeName, schemaN
     if (state === 'ready') {
         const specPaths = contextFiles.specs ?? [];
         const tasksPath = tracksFile && tracksFileExists ? path.join(changeDir, tracksFile) : null;
+        const planPath = resolvePlanPath(contextFiles, changeDir);
         const pendingTaskCount = tasks.filter((task) => !task.done).length;
-        const gate = checkComprehensionGate(changeDir, specPaths, options.projectConfig ?? readProjectConfig(projectRoot), { tasksPath, pendingTaskCount });
+        const artifactPresence = buildArtifactPresence(contextFiles, pendingTaskCount);
+        const gate = checkComprehensionGate(changeDir, specPaths, options.projectConfig ?? readProjectConfig(projectRoot), { tasksPath, planPath, pendingTaskCount, artifactPresence });
         if (gate.active && !gate.passed && gate.info) {
             state = 'blocked';
             missingComprehension = true;
             comprehension = gate.info;
-            instruction = `Complete the comprehension quiz in /opsx:apply before implementation (score ≥ ${gate.info.thresholdPercent}% on proposal, design, specs, and tasks).`;
+            instruction = `Complete the comprehension quiz in /opsx:apply before implementation (score ≥ ${gate.info.thresholdPercent}% on proposal, design, specs, plan, and tasks; plan receives the majority of questions per questionAllocation).`;
         }
         else if (gate.active && gate.info) {
             comprehension = gate.info;
@@ -359,15 +377,32 @@ export async function applyInstructionsCommand(options) {
             }
             const tracksFile = schema.apply?.tracks ?? null;
             const tasksPath = tracksFile ? path.join(changeDir, tracksFile) : null;
+            const planPath = fs.existsSync(path.join(changeDir, 'plan.md'))
+                ? path.join(changeDir, 'plan.md')
+                : null;
+            const pendingTaskCount = tasksPath && fs.existsSync(tasksPath)
+                ? parseTasksFile(fs.readFileSync(tasksPath, 'utf-8')).filter((t) => !t.done).length
+                : 0;
+            const contextFilesForPresence = {};
+            for (const artifact of schema.artifacts) {
+                const outputs = resolveArtifactOutputs(changeDir, artifact.generates);
+                if (outputs.length > 0) {
+                    contextFilesForPresence[artifact.id] = outputs;
+                }
+            }
+            const artifactPresence = buildArtifactPresence(contextFilesForPresence, pendingTaskCount);
             try {
                 const record = recordComprehensionPass({
                     changeDir,
                     specPaths,
                     tasksPath,
+                    planPath,
                     projectConfig,
                     scorePercent: options.score,
                     attempt: options.attempt ?? 1,
                     questionCount: options.questionCount ?? 0,
+                    pendingTaskCount,
+                    artifactPresence,
                 });
                 spinner?.stop();
                 if (options.json) {
@@ -453,11 +488,17 @@ export function printApplyInstructionsText(instructions) {
     if (state === 'blocked' && missingComprehension && comprehension) {
         console.log('### ⚠️ Comprehension Required');
         console.log();
-        console.log(`Pass the spec and task comprehension quiz (score ≥ ${comprehension.thresholdPercent}%) before implementation.`);
-        console.log(`Questions: ${comprehension.questionCount}`);
+        console.log(`Pass the comprehension quiz (score ≥ ${comprehension.thresholdPercent}%) before implementation.`);
+        console.log(`Questions: ${comprehension.questionCount} (${comprehension.optionsPerQuestion} options each)`);
+        const allocationParts = Object.entries(comprehension.questionAllocation)
+            .filter(([, count]) => (count ?? 0) > 0)
+            .map(([category, count]) => `${category}×${count}`);
+        if (allocationParts.length > 0) {
+            console.log(`Allocation: ${allocationParts.join(', ')}`);
+        }
         console.log(`Specs: ${comprehension.requirementCount} requirements, ${comprehension.scenarioCount} scenarios; Tasks: ${comprehension.pendingTaskCount} pending`);
         if (comprehension.bestScorePercent !== undefined) {
-            console.log(`Previous score: ${comprehension.bestScorePercent}% (specs changed — retake required)`);
+            console.log(`Previous score: ${comprehension.bestScorePercent}% (artifacts changed — retake required)`);
         }
         console.log('Complete the quiz via /opsx:apply.');
         console.log();

package/dist/commands/workflow/shared.d.ts

@@ -23,6 +23,8 @@ export interface ApplyComprehensionInfo {
     thresholdPercent: number;
     bestScorePercent?: number;
     questionCount: number;
+    questionAllocation: Record<string, number>;
+    optionsPerQuestion: number;
     requirementCount: number;
     scenarioCount: number;
     pendingTaskCount: number;

package/dist/core/completions/command-registry.js

@@ -191,6 +191,25 @@ export const COMMAND_REGISTRY = [
                 description: 'Schema override',
                 takesValue: true,
             },
+            {
+                name: 'record-comprehension-pass',
+                description: 'Record a successful comprehension quiz pass (use with instructions apply)',
+            },
+            {
+                name: 'score',
+                description: 'Quiz score 0-100 (required with --record-comprehension-pass)',
+                takesValue: true,
+            },
+            {
+                name: 'attempt',
+                description: 'Quiz attempt number',
+                takesValue: true,
+            },
+            {
+                name: 'question-count',
+                description: 'Number of quiz questions taken',
+                takesValue: true,
+            },
             COMMON_FLAGS.json,
             COMMON_FLAGS.store,
         ],

package/dist/core/comprehension/fingerprint.d.ts

@@ -1,5 +1,14 @@
+export interface ApplyArtifactFingerprintInput {
+    specPaths: string[];
+    tasksPath?: string | null;
+    planPath?: string | null;
+}
 /**
- * SHA-256 fingerprint of delta spec and optional tasks file contents.
+ * SHA-256 fingerprint of delta specs and optional plan/tasks file contents.
+ */
+export declare function fingerprintApplyArtifacts(input: ApplyArtifactFingerprintInput): string;
+/**
+ * @deprecated Use fingerprintApplyArtifacts
  */
 export declare function fingerprintSpecFiles(specPaths: string[], tasksPath?: string | null): string;
 //# sourceMappingURL=fingerprint.d.ts.map

package/dist/core/comprehension/fingerprint.js

@@ -1,25 +1,33 @@
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
+function hashFileContent(hash, label, filePath) {
+    hash.update(`${label}:`);
+    hash.update(filePath);
+    hash.update('\0');
+    hash.update(readFileSync(filePath, 'utf-8'));
+    hash.update('\0');
+}
 /**
- * SHA-256 fingerprint of delta spec and optional tasks file contents.
+ * SHA-256 fingerprint of delta specs and optional plan/tasks file contents.
  */
-export function fingerprintSpecFiles(specPaths, tasksPath) {
-    const sorted = [...specPaths].sort();
+export function fingerprintApplyArtifacts(input) {
+    const sorted = [...input.specPaths].sort();
     const hash = createHash('sha256');
     for (const specPath of sorted) {
-        hash.update('spec:');
-        hash.update(specPath);
-        hash.update('\0');
-        hash.update(readFileSync(specPath, 'utf-8'));
-        hash.update('\0');
+        hashFileContent(hash, 'spec', specPath);
     }
-    if (tasksPath && existsSync(tasksPath)) {
-        hash.update('tasks:');
-        hash.update(tasksPath);
-        hash.update('\0');
-        hash.update(readFileSync(tasksPath, 'utf-8'));
-        hash.update('\0');
+    if (input.planPath && existsSync(input.planPath)) {
+        hashFileContent(hash, 'plan', input.planPath);
+    }
+    if (input.tasksPath && existsSync(input.tasksPath)) {
+        hashFileContent(hash, 'tasks', input.tasksPath);
     }
     return hash.digest('hex');
 }
+/**
+ * @deprecated Use fingerprintApplyArtifacts
+ */
+export function fingerprintSpecFiles(specPaths, tasksPath) {
+    return fingerprintApplyArtifacts({ specPaths, tasksPath });
+}
 //# sourceMappingURL=fingerprint.js.map

package/dist/core/comprehension/index.d.ts

@@ -1,15 +1,18 @@
 import type { ProjectConfig } from '../project-config.js';
 import { type ComprehensionPassRecord } from './pass-record.js';
+import { OPTIONS_PER_QUESTION, type ArtifactPresence, type QuestionAllocation } from './stats.js';
 export { DEFAULT_COMPREHENSION_CONFIG, resolveComprehensionConfig, type ComprehensionConfig, } from './config.js';
-export { fingerprintSpecFiles } from './fingerprint.js';
+export { fingerprintApplyArtifacts, fingerprintSpecFiles } from './fingerprint.js';
 export { COMPREHENSION_PASS_FILENAME, COMPREHENSION_SESSION_FILENAME, buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, type ComprehensionPassRecord, } from './pass-record.js';
-export { computeQuestionCount, computeSpecStats, countSpecStats, type SpecStats } from './stats.js';
+export { computeQuestionAllocation, computeQuestionCount, computeSpecStats, countSpecStats, OPTIONS_PER_QUESTION, type ArtifactPresence, type QuestionAllocation, type QuestionCategory, type SpecStats, } from './stats.js';
 export interface ComprehensionGateInfo {
     required: boolean;
     passed: boolean;
     thresholdPercent: number;
     bestScorePercent?: number;
     questionCount: number;
+    questionAllocation: QuestionAllocation;
+    optionsPerQuestion: number;
     requirementCount: number;
     scenarioCount: number;
     pendingTaskCount: number;
@@ -17,7 +20,9 @@ export interface ComprehensionGateInfo {
 }
 export interface ComprehensionGateOptions {
     tasksPath?: string | null;
+    planPath?: string | null;
     pendingTaskCount?: number;
+    artifactPresence?: ArtifactPresence;
 }
 export interface ComprehensionGateResult {
     active: boolean;
@@ -40,10 +45,13 @@ export declare function recordComprehensionPass(input: {
     changeDir: string;
     specPaths: string[];
     tasksPath?: string | null;
+    planPath?: string | null;
     projectConfig: ProjectConfig | null | undefined;
     scorePercent: number;
     attempt: number;
     questionCount: number;
     pendingTaskCount?: number;
+    artifactPresence?: ArtifactPresence;
 }): ComprehensionPassRecord;
+export { OPTIONS_PER_QUESTION as comprehensionOptionsPerQuestion };
 //# sourceMappingURL=index.d.ts.map

package/dist/core/comprehension/index.js

@@ -1,11 +1,11 @@
 import { resolveComprehensionConfig } from './config.js';
-import { fingerprintSpecFiles } from './fingerprint.js';
+import { fingerprintApplyArtifacts } from './fingerprint.js';
 import { buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, } from './pass-record.js';
-import { computeSpecStats } from './stats.js';
+import { computeSpecStats, OPTIONS_PER_QUESTION, } from './stats.js';
 export { DEFAULT_COMPREHENSION_CONFIG, resolveComprehensionConfig, } from './config.js';
-export { fingerprintSpecFiles } from './fingerprint.js';
+export { fingerprintApplyArtifacts, fingerprintSpecFiles } from './fingerprint.js';
 export { COMPREHENSION_PASS_FILENAME, COMPREHENSION_SESSION_FILENAME, buildPassRecord, deleteSessionRecord, isPassValid, readPassRecord, writePassRecord, } from './pass-record.js';
-export { computeQuestionCount, computeSpecStats, countSpecStats } from './stats.js';
+export { computeQuestionAllocation, computeQuestionCount, computeSpecStats, countSpecStats, OPTIONS_PER_QUESTION, } from './stats.js';
 /**
  * Evaluate whether apply is blocked by the comprehension gate.
  */
@@ -13,17 +13,19 @@ export function checkComprehensionGate(changeDir, specPaths, projectConfig, gate
     const config = resolveComprehensionConfig(projectConfig);
     const pendingTaskCount = gateOptions.pendingTaskCount ?? 0;
     const tasksPath = gateOptions.tasksPath ?? null;
+    const planPath = gateOptions.planPath ?? null;
+    const artifactPresence = gateOptions.artifactPresence ?? {};
     if (!config.enabled) {
         return { active: false, passed: true };
     }
     if (specPaths.length === 0) {
         return { active: false, passed: true };
     }
-    const stats = computeSpecStats(specPaths, config, pendingTaskCount);
+    const stats = computeSpecStats(specPaths, config, pendingTaskCount, artifactPresence);
     if (stats.requirementCount === 0) {
         return { active: false, passed: true };
     }
-    const fingerprint = fingerprintSpecFiles(specPaths, tasksPath);
+    const fingerprint = fingerprintApplyArtifacts({ specPaths, tasksPath, planPath });
     const record = readPassRecord(changeDir);
     const passed = isPassValid(record, fingerprint);
     const info = {
@@ -31,6 +33,8 @@ export function checkComprehensionGate(changeDir, specPaths, projectConfig, gate
         passed,
         thresholdPercent: config.thresholdPercent,
         questionCount: stats.questionCount,
+        questionAllocation: stats.questionAllocation,
+        optionsPerQuestion: stats.optionsPerQuestion,
         requirementCount: stats.requirementCount,
         scenarioCount: stats.scenarioCount,
         pendingTaskCount: stats.pendingTaskCount,
@@ -62,8 +66,12 @@ export function recordComprehensionPass(input) {
     }
     const stats = input.questionCount > 0
         ? { questionCount: input.questionCount }
-        : computeSpecStats(input.specPaths, config, input.pendingTaskCount ?? 0);
-    const fingerprint = fingerprintSpecFiles(input.specPaths, input.tasksPath);
+        : computeSpecStats(input.specPaths, config, input.pendingTaskCount ?? 0, input.artifactPresence ?? {});
+    const fingerprint = fingerprintApplyArtifacts({
+        specPaths: input.specPaths,
+        tasksPath: input.tasksPath,
+        planPath: input.planPath,
+    });
     const record = buildPassRecord({
         scorePercent: input.scorePercent,
         thresholdPercent: config.thresholdPercent,
@@ -75,4 +83,5 @@ export function recordComprehensionPass(input) {
     deleteSessionRecord(input.changeDir);
     return record;
 }
+export { OPTIONS_PER_QUESTION as comprehensionOptionsPerQuestion };
 //# sourceMappingURL=index.js.map

package/dist/core/comprehension/stats.d.ts

@@ -1,10 +1,27 @@
 import type { ComprehensionConfig } from './config.js';
+export declare const OPTIONS_PER_QUESTION = 3;
+export type QuestionCategory = 'plan' | 'specs' | 'design' | 'proposal' | 'tasks';
+export type QuestionAllocation = Partial<Record<QuestionCategory, number>>;
+export interface ArtifactPresence {
+    hasPlan?: boolean;
+    hasProposal?: boolean;
+    hasDesign?: boolean;
+    hasSpecs?: boolean;
+    hasTasks?: boolean;
+}
 export interface SpecStats {
     requirementCount: number;
     scenarioCount: number;
     pendingTaskCount: number;
     questionCount: number;
+    questionAllocation: QuestionAllocation;
+    optionsPerQuestion: number;
 }
+/**
+ * Distribute quiz questions across artifact categories.
+ * When plan exists, plan receives ceil(total/2) — strictly more than any other category.
+ */
+export declare function computeQuestionAllocation(total: number, presence: ArtifactPresence): QuestionAllocation;
 /**
  * Count requirements and scenarios across delta spec files.
  */
@@ -14,5 +31,5 @@ export declare function countSpecStats(specPaths: string[]): Pick<SpecStats, 're
  * clamp(min, max, round(req * 0.6 + scenarios * 0.15 + pendingTasks * 0.15)).
  */
 export declare function computeQuestionCount(requirementCount: number, scenarioCount: number, pendingTaskCount: number, config: Pick<ComprehensionConfig, 'minQuestions' | 'maxQuestions'>): number;
-export declare function computeSpecStats(specPaths: string[], config: Pick<ComprehensionConfig, 'minQuestions' | 'maxQuestions'>, pendingTaskCount?: number): SpecStats;
+export declare function computeSpecStats(specPaths: string[], config: Pick<ComprehensionConfig, 'minQuestions' | 'maxQuestions'>, pendingTaskCount?: number, presence?: ArtifactPresence): SpecStats;
 //# sourceMappingURL=stats.d.ts.map

package/dist/core/comprehension/stats.js

@@ -1,6 +1,89 @@
 import { readFileSync } from 'node:fs';
 import { parseDeltaSpec } from '../parsers/requirement-blocks.js';
 const SCENARIO_HEADER_REGEX = /^####\s*Scenario:/gim;
+export const OPTIONS_PER_QUESTION = 3;
+const NON_PLAN_PRIORITY = ['specs', 'design', 'proposal', 'tasks'];
+function isCategoryPresent(category, presence) {
+    switch (category) {
+        case 'plan':
+            return presence.hasPlan === true;
+        case 'specs':
+            return presence.hasSpecs === true;
+        case 'design':
+            return presence.hasDesign === true;
+        case 'proposal':
+            return presence.hasProposal === true;
+        case 'tasks':
+            return presence.hasTasks === true;
+        default:
+            return false;
+    }
+}
+function sumAllocation(allocation) {
+    return Object.values(allocation).reduce((sum, n) => sum + (n ?? 0), 0);
+}
+/**
+ * Distribute quiz questions across artifact categories.
+ * When plan exists, plan receives ceil(total/2) — strictly more than any other category.
+ */
+export function computeQuestionAllocation(total, presence) {
+    if (total <= 0) {
+        return {};
+    }
+    if (presence.hasPlan) {
+        const allocation = {};
+        const planQuota = Math.ceil(total / 2);
+        allocation.plan = planQuota;
+        let remainder = total - planQuota;
+        for (const category of NON_PLAN_PRIORITY) {
+            if (remainder <= 0) {
+                break;
+            }
+            if (!isCategoryPresent(category, presence)) {
+                continue;
+            }
+            allocation[category] = (allocation[category] ?? 0) + 1;
+            remainder--;
+        }
+        const presentOthers = NON_PLAN_PRIORITY.filter((category) => isCategoryPresent(category, presence));
+        let index = 0;
+        while (remainder > 0 && presentOthers.length > 0) {
+            const category = presentOthers[index % presentOthers.length];
+            allocation[category] = (allocation[category] ?? 0) + 1;
+            remainder--;
+            index++;
+        }
+        return allocation;
+    }
+    return computeQuestionAllocationEven(total, presence);
+}
+/**
+ * Even split when plan is absent: at least one per present category, extras specs-first.
+ */
+function computeQuestionAllocationEven(total, presence) {
+    const present = NON_PLAN_PRIORITY.filter((category) => isCategoryPresent(category, presence));
+    if (present.length === 0) {
+        return {};
+    }
+    const allocation = {};
+    let assigned = 0;
+    for (const category of present) {
+        if (assigned >= total) {
+            break;
+        }
+        allocation[category] = 1;
+        assigned++;
+    }
+    let remainder = total - assigned;
+    let index = 0;
+    while (remainder > 0) {
+        const category = present[index % present.length];
+        allocation[category] = (allocation[category] ?? 0) + 1;
+        remainder--;
+        index++;
+    }
+    return allocation;
+}
 function countScenariosInBlock(raw) {
     const matches = raw.match(SCENARIO_HEADER_REGEX);
     return matches?.length ?? 0;
@@ -33,9 +116,18 @@ export function computeQuestionCount(requirementCount, scenarioCount, pendingTas
     const raw = Math.round(requirementCount * 0.6 + scenarioCount * 0.15 + pendingTaskCount * 0.15);
     return clamp(config.minQuestions, config.maxQuestions, raw);
 }
-export function computeSpecStats(specPaths, config, pendingTaskCount = 0) {
+export function computeSpecStats(specPaths, config, pendingTaskCount = 0, presence = {}) {
     const { requirementCount, scenarioCount } = countSpecStats(specPaths);
     const questionCount = computeQuestionCount(requirementCount, scenarioCount, pendingTaskCount, config);
-    return { requirementCount, scenarioCount, pendingTaskCount, questionCount };
+    const questionAllocation = computeQuestionAllocation(questionCount, presence);
+    const allocationTotal = sumAllocation(questionAllocation);
+    return {
+        requirementCount,
+        scenarioCount,
+        pendingTaskCount,
+        questionCount: allocationTotal > 0 ? allocationTotal : questionCount,
+        questionAllocation,
+        optionsPerQuestion: OPTIONS_PER_QUESTION,
+    };
 }
 //# sourceMappingURL=stats.js.map

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>\`).
 
@@ -57,7 +58,7 @@ ${COMPREHENSION_QUIZ_GUIDANCE}
 
    After comprehension is passed (or not required), read every file path listed under \`contextFiles\` from the apply instructions output.
    The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
+   - **spec-driven**: proposal, specs, design, plan, tasks
    - Other schemas: follow the contextFiles from CLI output
 
 6. **Show current progress**
@@ -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>\`).
 
@@ -226,7 +227,7 @@ ${COMPREHENSION_QUIZ_GUIDANCE}
 
    After comprehension is passed (or not required), read every file path listed under \`contextFiles\` from the apply instructions output.
    The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, tasks
+   - **spec-driven**: proposal, specs, design, plan, tasks
    - Other schemas: follow the contextFiles from CLI output
 
 6. **Show current progress**

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.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   - 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 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- 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`, `contextFiles.plan`, and `contextFiles.tasks` (or the `tasks` array in apply JSON)\n     - Use `comprehension.questionCount` and `comprehension.questionAllocation` from the JSON\n\n   **Generate questions**\n   - Create exactly `comprehension.questionCount` multiple-choice questions\n   - **Follow `comprehension.questionAllocation`** \u2014 generate the exact count per category (e.g. plan\u00D74, specs\u00D71); do not invent your own split\n   - Each question maps 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     - **Plan**: code map, file targets, test plan, sequencing, or alignment with design from `plan.md`\n     - **Tasks**: conceptual understanding of the implementation approach from pending (unchecked) tasks\n   - Do NOT use completed tasks as question sources\n   - Each question: **3 options** (`comprehension.optionsPerQuestion`, default 3) \u2014 1 correct from source substance, 2 plausible distractors from other proposal/design/spec/plan/task substance in the change\n\n   **Plan question quality**\n   - Test code map, file targets, test plan, sequencing, or alignment with design\n   - **Forbidden**: section numbers, verbatim headings, trivia answerable without reading plan substance\n\n   **Task question quality**\n   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design/plan\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/spec/plan/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   plan\u00D7N, specs\u00D7N, design\u00D7N, proposal\u00D7N, tasks\u00D7N \u2192 <questionCount> questions (3 options each)\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,41 +4,44 @@
  * 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.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
+     - Read \`contextFiles.proposal\`, \`contextFiles.design\`, \`contextFiles.specs\`, \`contextFiles.plan\`, and \`contextFiles.tasks\` (or the \`tasks\` array in apply JSON)
+     - Use \`comprehension.questionCount\` and \`comprehension.questionAllocation\` from the JSON
 
    **Generate questions**
    - Create exactly \`comprehension.questionCount\` multiple-choice questions
-   - Each question MUST map to one artifact category:
+   - **Follow \`comprehension.questionAllocation\`** — generate the exact count per category (e.g. plan×4, specs×1); do not invent your own split
+   - Each question maps 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
+     - **Plan**: code map, file targets, test plan, sequencing, or alignment with design from \`plan.md\`
+     - **Tasks**: conceptual understanding of the implementation approach from pending (unchecked) tasks
    - Do NOT use completed tasks as question sources
-   - Each question: 4 options (1 correct from the source substance, 3 plausible distractors from other proposal/design/requirements/scenarios/task substance in the change)
+   - Each question: **3 options** (\`comprehension.optionsPerQuestion\`, default 3) — 1 correct from source substance, 2 plausible distractors from other proposal/design/spec/plan/task substance in the change
+
+   **Plan question quality**
+   - Test code map, file targets, test plan, sequencing, or alignment with design
+   - **Forbidden**: section numbers, verbatim headings, trivia answerable without reading plan substance
 
    **Task question quality**
-   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design
+   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design/plan
    - **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?"
 
-   **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)
+   ${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 proposal/design/requirement/scenario/task sources (avoid \`used_sources\`)
+   - Generate a NEW question set using different proposal/design/spec/plan/task sources (avoid \`used_sources\`)
    - Retry until pass
 
    **On pass**
@@ -52,7 +55,7 @@ export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required be
    \`\`\`
    ## Applying: <change-name> — comprehension check
 
-   Proposal, design, specs (<requirementCount> requirements, <scenarioCount> scenarios), tasks (<pendingTaskCount> pending) → <questionCount> questions
+   plan×N, specs×N, design×N, proposal×N, tasks×N → <questionCount> questions (3 options each)
 
    Question 1/N: ...
    ...
@@ -62,5 +65,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
@@ -94,7 +95,7 @@ The artifact types and their purpose depend on the schema. Use the \`instruction
 
 Common artifact patterns:
 
-**spec-driven schema** (proposal → specs → design → tasks):
+**spec-driven schema** (proposal → specs → design → plan → tasks):
 - **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
   - The Capabilities section is critical - each capability listed will need a spec file.
 - **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the 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
@@ -215,7 +216,7 @@ The artifact types and their purpose depend on the schema. Use the \`instruction
 
 Common artifact patterns:
 
-**spec-driven schema** (proposal → specs → design → tasks):
+**spec-driven schema** (proposal → specs → design → plan → tasks):
 - **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
   - The Capabilities section is critical - each capability listed will need a spec file.
 - **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the 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/onboard.js

@@ -47,7 +47,7 @@ I'll walk you through a complete change cycle—from idea to implementation—us
 1. Pick a small, real task in your codebase
 2. Explore the problem briefly
 3. Create a change (the container for our work)
-4. Build the artifacts: proposal → specs → design → tasks
+4. Build the artifacts: proposal → specs → design → plan → tasks
 5. Implement the tasks
 6. Archive the completed change
 
@@ -170,7 +170,7 @@ Now let's create a change to hold our work.
 \`\`\`
 ## Creating a Change
 
-A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives at the \`changeRoot\` reported by \`openspec status --change "<name>" --json\` and holds your artifacts—proposal, specs, design, tasks.
+A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives at the \`changeRoot\` reported by \`openspec status --change "<name>" --json\` and holds your artifacts—proposal, specs, design, plan, tasks.
 
 Let me create one for our task.
 \`\`\`

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

@@ -1,14 +1,16 @@
 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',
-        description: 'Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.',
+        description: 'Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, plan, and tasks ready for implementation.',
         instructions: `Propose a new change - create the change and generate all artifacts in one step.
 
 I'll create a change with artifacts:
 - proposal.md (what & why)
 - design.md (how)
+- plan.md (file-level implementation plan)
 - tasks.md (implementation steps)
 
 When ready to implement, run /opsx:apply
@@ -25,7 +27,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 +78,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**
@@ -124,6 +126,7 @@ export function getOpsxProposeCommandTemplate() {
 I'll create a change with artifacts:
 - proposal.md (what & why)
 - design.md (how)
+- plan.md (file-level implementation plan)
 - tasks.md (implementation steps)
 
 When ready to implement, run /opsx:apply
@@ -140,7 +143,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 +194,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.03",
+  "version": "1.0.05",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",

package/schemas/spec-driven/schema.yaml

@@ -1,6 +1,6 @@
 name: spec-driven
 version: 1
-description: Default OpenSpec workflow - proposal → specs → design → tasks
+description: Default OpenSpec workflow - proposal → specs → design → plan → tasks
 artifacts:
   - id: proposal
     generates: proposal.md
@@ -24,7 +24,7 @@ artifacts:
       Keep it concise (1-2 pages). Focus on the "why" not the "how" -
       implementation details belong in design.md.
 
-      This is the foundation - specs, design, and tasks all build on this.
+      This is the foundation - specs, design, plan, and tasks all build on this.
     requires: []
 
   - id: specs
@@ -110,6 +110,26 @@ artifacts:
     requires:
       - proposal
 
+  - id: plan
+    generates: plan.md
+    description: File-level implementation plan with code map
+    template: plan.md
+    instruction: |
+      Create a concrete implementation plan from design and specs.
+
+      Sections:
+      - **Code map**: Files to create, modify, or delete
+      - **Implementation order**: Sequenced steps at file/module level
+      - **Test plan**: How to verify the change
+      - **Risks**: Known risks with mitigations ([Risk] → Mitigation)
+      - **Done definition**: Objective criteria for completion
+
+      Do NOT restate behavioral requirements — link to specs.
+      Do NOT duplicate design decisions — reference design.md.
+    requires:
+      - specs
+      - design
+
   - id: tasks
     generates: tasks.md
     description: Implementation checklist with trackable tasks
@@ -139,14 +159,17 @@ artifacts:
       - [ ] 2.2 Add CSV formatting utilities
       ```
 
-      Reference specs for what needs to be built, design for how to build it.
+      Derive tasks from plan.md code map. Reference specs for what to build,
+      design for architectural decisions, and plan for file-level targets.
+      Include file/module references where helpful.
       Each task should be verifiable - you know when it's done.
     requires:
       - specs
       - design
+      - plan
 
 apply:
-  requires: [tasks]
+  requires: [plan, tasks]
   tracks: tasks.md
   instruction: |
     Read context files, work through pending tasks, mark complete as you go.

package/schemas/spec-driven/templates/plan.md

@@ -0,0 +1,19 @@
+## Code Map
+
+<!-- files to create/modify/delete -->
+
+## Implementation Order
+
+<!-- sequenced steps at file/module level -->
+
+## Test Plan
+
+<!-- how to verify -->
+
+## Risks
+
+<!-- [Risk] → Mitigation -->
+
+## Done Definition
+
+<!-- objective completion criteria -->