gspec 1.10.0 → 1.13.0

package/dist/claude/gspec-migrate/SKILL.md

@@ -5,7 +5,7 @@ description: Migrate existing gspec files to the current format when upgrading t
 
 You are a Technical Documentation Migration Specialist.
 
-Your task is to update existing gspec specification documents to match the current gspec format (version 1.10.0). You preserve all substantive content while ensuring documents follow the latest structural conventions.
+Your task is to update existing gspec specification documents to match the current spec format (spec-version v1). You preserve all substantive content while ensuring documents follow the latest structural conventions.
 
 ---
 
@@ -19,16 +19,17 @@ Scan the `gspec/` directory for all Markdown files:
 
 
 For each file, check the YAML frontmatter at the top of the file:
-- If the file starts with `---` followed by YAML content and another `---`, read the `gspec-version` field
+- If the file starts with `---` followed by YAML content and another `---`, read the `spec-version` field (also check for the legacy `gspec-version` field)
 - If no frontmatter exists, the file predates version tracking
-- If `gspec-version` matches `1.10.0`, the file is current — skip it
+- If `spec-version` matches `v1`, the file is current — skip it
+- If the file has `gspec-version` (old field name) instead of `spec-version`, it needs migration regardless of value
 
 Present an inventory to the user:
 
 > **gspec File Inventory:**
 > - `gspec/profile.md` — no version (needs migration)
-> - `gspec/stack.md` — version 1.0.3 (needs migration)
-> - `gspec/style.md` — version 1.10.0 (current, skipping)
+> - `gspec/stack.md` — gspec-version 1.0.3 (needs migration — old field name)
+> - `gspec/style.md` — spec-version v1 (current, skipping)
 > - `gspec/features/user-auth.md` — no version (needs migration)
 
 Ask the user to confirm which files to migrate, or confirm all.
@@ -63,21 +64,22 @@ For each file to migrate:
 5. **Add or update the frontmatter** — Ensure the file starts with:
    ```
    ---
-   gspec-version: 1.10.0
+   spec-version: v1
    ---
    ```
+   If the file has the old `gspec-version` field, rename it to `spec-version` and set the value to `v1`.
 6. **Present the proposed changes** to the user before writing. Show what sections are being reorganized, what is being added, and confirm no content is being lost.
 
 ### Phase 4: Verify — Confirm Migration
 
 After migrating all files:
 
-1. **Verify every migrated file** has the correct frontmatter
+1. **Verify every migrated file** has the correct frontmatter (`spec-version: v1`)
 2. **Verify no content was lost** — Briefly summarize what was preserved and any content that was relocated
 3. **Present a completion summary**:
 
 > **Migration Complete:**
-> - 4 files migrated to version 1.10.0
+> - 4 files migrated to spec-version v1
 > - 2 files were already current (skipped)
 > - Content preserved in all files
 > - Sections reorganized: [list any structural changes]
@@ -100,8 +102,9 @@ After migrating all files:
 
 **Frontmatter handling:**
 - If the file has no frontmatter, add it at the very top
-- If the file has frontmatter without `gspec-version`, add the field
-- If the file has an outdated `gspec-version`, update it
+- If the file has the old `gspec-version` field, rename it to `spec-version`
+- If the file has frontmatter without `spec-version`, add the field
+- If the file has an outdated `spec-version`, update it
 - Preserve any other frontmatter fields that may exist
 
 ---

package/dist/claude/gspec-practices/SKILL.md

@@ -22,10 +22,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/practices.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/claude/gspec-profile/SKILL.md

@@ -22,10 +22,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/profile.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/claude/gspec-research/SKILL.md

@@ -162,7 +162,7 @@ After writing `gspec/research.md`, ask the user:
    - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
    - Success Metrics
    - Implementation Context (standard portability note)
-   - Begin the file with YAML frontmatter: `---\ngspec-version: 1.10.0\n---`
+   - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`
 2. **Name the file** descriptively based on the feature (e.g., `gspec/features/csv-export.md`, `gspec/features/onboarding-wizard.md`)
 3. **Keep the PRD portable** — use generic role descriptions (not project-specific persona names), define success metrics in terms of the feature's own outcomes (not project-level KPIs), and describe UX behavior generically (not tied to a specific design system). The PRD should be reusable across projects.
 4. **Keep the PRD product-focused** — describe *what* and *why*, not *how*. Implementation details belong in the code, not the PRD.
@@ -178,10 +178,10 @@ After writing `gspec/research.md`, ask the user:
 
 - Save the primary output as `gspec/research.md` in the root of the project, create the `gspec` folder if it doesn't exist
 - If the user accepts feature generation (Phase 7), also save feature PRDs to `gspec/features/`
-- Begin `gspec/research.md` with YAML frontmatter containing the gspec version:
+- Begin `gspec/research.md` with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -198,7 +198,7 @@ The `gspec/research.md` file must follow this structure:
 
 ```markdown
 ---
-gspec-version: 1.10.0
+spec-version: v1
 ---
 
 # Competitive Research

package/dist/claude/gspec-stack/SKILL.md

@@ -22,10 +22,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/stack.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/claude/gspec-style/SKILL.md

@@ -24,10 +24,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/style.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/codex/gspec-analyze/SKILL.md

@@ -128,7 +128,7 @@ When updating specs to resolve a discrepancy:
 
 - **Surgical updates only** — change the minimum text needed to resolve the conflict
 - **Preserve format and tone** — match the existing document's style, heading structure, and voice
-- **Preserve `gspec-version` frontmatter** — do not alter or remove it
+- **Preserve `spec-version` frontmatter** — do not alter or remove it
 - **Do not rewrite sections** — if a one-line change resolves the conflict, make a one-line change
 - **Do not add changelog annotations** — the git history captures what changed
 

package/dist/codex/gspec-architect/SKILL.md

@@ -42,10 +42,10 @@ All of these provide essential context. If any are missing, note the gap and mak
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/architecture.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/codex/gspec-feature/SKILL.md

@@ -82,10 +82,10 @@ Feature PRDs are designed to be **portable across projects**. A feature spec wri
 - Output one or more Markdown documents — **one per feature**
 - Save each file to the `gspec/features/` folder in the root of the project, create it if it doesn't exist
 - Name each file based on the feature (e.g., `user-authentication.md`, `dashboard-analytics.md`)
-- Begin each file with YAML frontmatter containing the gspec version:
+- Begin each file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/codex/gspec-implement/SKILL.md

@@ -62,8 +62,9 @@ Present this summary to the user so they understand the starting point. If **all
    - Identify files to create or modify
    - Note dependencies on prior phases
    - Include an estimated scope (small/medium/large)
-3. **Define test expectations per phase** — For each phase, specify what tests will be run to verify correctness before moving on (unit tests, integration tests, build verification, etc.)
-4. **Present the plan** — Show the user the full phased plan with clear phase boundaries and ask for approval
+3. **Account for every unchecked capability** — The plan must explicitly place every unchecked capability from in-scope feature PRDs into a phase **or** list it under a "Proposed to Defer" section with a reason. No unchecked capability may be silently omitted from the plan. The user reviews and approves what gets deferred at plan approval time.
+4. **Define test expectations per phase** — For each phase, specify what tests will be run to verify correctness before moving on (unit tests, integration tests, build verification, etc.)
+5. **Present the plan** — Show the user the full phased plan with clear phase boundaries and ask for approval
 
 **Wait for user approval before proceeding to Phase 3.** The user may reorder phases, adjust scope, or split/merge phases.
 
@@ -109,7 +110,7 @@ Present a brief scaffold summary to the user before proceeding to feature implem
    b. **Follow the practices** — Adhere to coding standards, testing philosophy, pipeline structure, and conventions from `gspec/practices.md`
    c. **Follow the style** — Apply the design system, tokens, and icon library from `gspec/style.md`. The style is the single authority for icon library choices. Component libraries (e.g., shadcn/ui) are defined in `gspec/stack.md`.
    d. **Satisfy the requirements** — Trace each piece of code back to a functional requirement in the feature PRD (if available) or to the user's stated goals and the approved implementation plan
-3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `gspec-version` YAML frontmatter. If a file lacks frontmatter, add `---\ngspec-version: 1.10.0\n---` at the top.
+3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `spec-version` YAML frontmatter. If a file lacks frontmatter, add `---\nspec-version: v1\n---` at the top.
 4. **Run tests** — Execute the tests defined for this phase (and any existing tests to catch regressions). Fix any failures before proceeding.
 6. **Surface new gaps** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 7. **Pause and report** — After completing the phase and confirming tests pass, present a phase completion summary to the user:
@@ -129,8 +130,8 @@ After implementation:
 1. **Walk through each functional requirement** from the feature PRD (if available) or the approved implementation plan and confirm it's satisfied
 2. **Review against acceptance criteria** — For each capability in the feature PRDs, check that every acceptance criterion listed under it is satisfied. These sub-listed conditions are the definition of "done" for each capability. If any criterion is not met, the capability should not be marked `[x]`.
 3. **Check the Definition of Done** from `gspec/practices.md`
-4. **Note any deferred items** — Requirements that were intentionally postponed or descoped during implementation
-5. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were intentionally deferred. Present a final status summary:
+4. **Verify no unapproved deferrals** — Compare the final implementation against the approved plan. If any capability that was assigned to a phase was not implemented, **do not silently leave it unchecked**. Flag it to the user, explain why it wasn't completed, and get explicit approval before marking it as deferred. Only capabilities the user approved for deferral during planning (or explicitly approves now) may remain unchecked.
+5. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were approved for deferral by the user. Present a final status summary:
 
 > **Implementation Summary:**
 > - Feature X: 7/7 capabilities implemented (complete)
@@ -149,6 +150,7 @@ When you encounter something the specs don't fully cover during implementation:
 - **If the ambiguity is significant** (e.g., unclear user flow, missing data model, conflicting requirements), pause and consult the user rather than making silent assumptions
 - **Never silently implement unspecified behavior** that contradicts or significantly extends the original spec — ask first
 - **Never override explicit spec decisions** with your own preferences
+- **Never skip or descope a PRD capability without user approval** — ambiguity in *how* to implement something is not grounds for dropping it. If a capability seems too complex, unclear, or problematic, raise it with the user rather than omitting it
 
 ---
 
@@ -178,7 +180,7 @@ If the user specifies a feature, focus on that feature's **unchecked capabilitie
 
 ### When the user provides a prompt alongside existing features:
 
-The user's prompt takes priority for scoping. Use it to determine focus, and reference existing feature PRDs as supporting context rather than the sole driver.
+The user's prompt takes priority for scoping. Use it to determine focus, and reference existing feature PRDs as supporting context rather than the sole driver. However, if the user's prompt narrows scope such that some unchecked PRD capabilities will not be implemented this run, explicitly list those excluded capabilities in the plan under "Out of Scope for This Run" so the user can see what is being deferred and why.
 
 ---
 

package/dist/codex/gspec-migrate/SKILL.md

@@ -5,7 +5,7 @@ description: Migrate existing gspec files to the current format when upgrading t
 
 You are a Technical Documentation Migration Specialist.
 
-Your task is to update existing gspec specification documents to match the current gspec format (version 1.10.0). You preserve all substantive content while ensuring documents follow the latest structural conventions.
+Your task is to update existing gspec specification documents to match the current spec format (spec-version v1). You preserve all substantive content while ensuring documents follow the latest structural conventions.
 
 ---
 
@@ -19,16 +19,17 @@ Scan the `gspec/` directory for all Markdown files:
 
 
 For each file, check the YAML frontmatter at the top of the file:
-- If the file starts with `---` followed by YAML content and another `---`, read the `gspec-version` field
+- If the file starts with `---` followed by YAML content and another `---`, read the `spec-version` field (also check for the legacy `gspec-version` field)
 - If no frontmatter exists, the file predates version tracking
-- If `gspec-version` matches `1.10.0`, the file is current — skip it
+- If `spec-version` matches `v1`, the file is current — skip it
+- If the file has `gspec-version` (old field name) instead of `spec-version`, it needs migration regardless of value
 
 Present an inventory to the user:
 
 > **gspec File Inventory:**
 > - `gspec/profile.md` — no version (needs migration)
-> - `gspec/stack.md` — version 1.0.3 (needs migration)
-> - `gspec/style.md` — version 1.10.0 (current, skipping)
+> - `gspec/stack.md` — gspec-version 1.0.3 (needs migration — old field name)
+> - `gspec/style.md` — spec-version v1 (current, skipping)
 > - `gspec/features/user-auth.md` — no version (needs migration)
 
 Ask the user to confirm which files to migrate, or confirm all.
@@ -63,21 +64,22 @@ For each file to migrate:
 5. **Add or update the frontmatter** — Ensure the file starts with:
    ```
    ---
-   gspec-version: 1.10.0
+   spec-version: v1
    ---
    ```
+   If the file has the old `gspec-version` field, rename it to `spec-version` and set the value to `v1`.
 6. **Present the proposed changes** to the user before writing. Show what sections are being reorganized, what is being added, and confirm no content is being lost.
 
 ### Phase 4: Verify — Confirm Migration
 
 After migrating all files:
 
-1. **Verify every migrated file** has the correct frontmatter
+1. **Verify every migrated file** has the correct frontmatter (`spec-version: v1`)
 2. **Verify no content was lost** — Briefly summarize what was preserved and any content that was relocated
 3. **Present a completion summary**:
 
 > **Migration Complete:**
-> - 4 files migrated to version 1.10.0
+> - 4 files migrated to spec-version v1
 > - 2 files were already current (skipped)
 > - Content preserved in all files
 > - Sections reorganized: [list any structural changes]
@@ -100,8 +102,9 @@ After migrating all files:
 
 **Frontmatter handling:**
 - If the file has no frontmatter, add it at the very top
-- If the file has frontmatter without `gspec-version`, add the field
-- If the file has an outdated `gspec-version`, update it
+- If the file has the old `gspec-version` field, rename it to `spec-version`
+- If the file has frontmatter without `spec-version`, add the field
+- If the file has an outdated `spec-version`, update it
 - Preserve any other frontmatter fields that may exist
 
 ---

package/dist/codex/gspec-practices/SKILL.md

@@ -22,10 +22,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/practices.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/codex/gspec-profile/SKILL.md

@@ -22,10 +22,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/profile.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/codex/gspec-research/SKILL.md

@@ -162,7 +162,7 @@ After writing `gspec/research.md`, ask the user:
    - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
    - Success Metrics
    - Implementation Context (standard portability note)
-   - Begin the file with YAML frontmatter: `---\ngspec-version: 1.10.0\n---`
+   - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`
 2. **Name the file** descriptively based on the feature (e.g., `gspec/features/csv-export.md`, `gspec/features/onboarding-wizard.md`)
 3. **Keep the PRD portable** — use generic role descriptions (not project-specific persona names), define success metrics in terms of the feature's own outcomes (not project-level KPIs), and describe UX behavior generically (not tied to a specific design system). The PRD should be reusable across projects.
 4. **Keep the PRD product-focused** — describe *what* and *why*, not *how*. Implementation details belong in the code, not the PRD.
@@ -178,10 +178,10 @@ After writing `gspec/research.md`, ask the user:
 
 - Save the primary output as `gspec/research.md` in the root of the project, create the `gspec` folder if it doesn't exist
 - If the user accepts feature generation (Phase 7), also save feature PRDs to `gspec/features/`
-- Begin `gspec/research.md` with YAML frontmatter containing the gspec version:
+- Begin `gspec/research.md` with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -198,7 +198,7 @@ The `gspec/research.md` file must follow this structure:
 
 ```markdown
 ---
-gspec-version: 1.10.0
+spec-version: v1
 ---
 
 # Competitive Research

package/dist/codex/gspec-stack/SKILL.md

@@ -22,10 +22,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/stack.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/codex/gspec-style/SKILL.md

@@ -24,10 +24,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/style.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/cursor/gspec-analyze.mdc

@@ -127,7 +127,7 @@ When updating specs to resolve a discrepancy:
 
 - **Surgical updates only** — change the minimum text needed to resolve the conflict
 - **Preserve format and tone** — match the existing document's style, heading structure, and voice
-- **Preserve `gspec-version` frontmatter** — do not alter or remove it
+- **Preserve `spec-version` frontmatter** — do not alter or remove it
 - **Do not rewrite sections** — if a one-line change resolves the conflict, make a one-line change
 - **Do not add changelog annotations** — the git history captures what changed
 

package/dist/cursor/gspec-architect.mdc

@@ -41,10 +41,10 @@ All of these provide essential context. If any are missing, note the gap and mak
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/architecture.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/cursor/gspec-feature.mdc

@@ -81,10 +81,10 @@ Feature PRDs are designed to be **portable across projects**. A feature spec wri
 - Output one or more Markdown documents — **one per feature**
 - Save each file to the `gspec/features/` folder in the root of the project, create it if it doesn't exist
 - Name each file based on the feature (e.g., `user-authentication.md`, `dashboard-analytics.md`)
-- Begin each file with YAML frontmatter containing the gspec version:
+- Begin each file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/cursor/gspec-implement.mdc

@@ -61,8 +61,9 @@ Present this summary to the user so they understand the starting point. If **all
    - Identify files to create or modify
    - Note dependencies on prior phases
    - Include an estimated scope (small/medium/large)
-3. **Define test expectations per phase** — For each phase, specify what tests will be run to verify correctness before moving on (unit tests, integration tests, build verification, etc.)
-4. **Present the plan** — Show the user the full phased plan with clear phase boundaries and ask for approval
+3. **Account for every unchecked capability** — The plan must explicitly place every unchecked capability from in-scope feature PRDs into a phase **or** list it under a "Proposed to Defer" section with a reason. No unchecked capability may be silently omitted from the plan. The user reviews and approves what gets deferred at plan approval time.
+4. **Define test expectations per phase** — For each phase, specify what tests will be run to verify correctness before moving on (unit tests, integration tests, build verification, etc.)
+5. **Present the plan** — Show the user the full phased plan with clear phase boundaries and ask for approval
 
 **Wait for user approval before proceeding to Phase 3.** The user may reorder phases, adjust scope, or split/merge phases.
 
@@ -108,7 +109,7 @@ Present a brief scaffold summary to the user before proceeding to feature implem
    b. **Follow the practices** — Adhere to coding standards, testing philosophy, pipeline structure, and conventions from `gspec/practices.md`
    c. **Follow the style** — Apply the design system, tokens, and icon library from `gspec/style.md`. The style is the single authority for icon library choices. Component libraries (e.g., shadcn/ui) are defined in `gspec/stack.md`.
    d. **Satisfy the requirements** — Trace each piece of code back to a functional requirement in the feature PRD (if available) or to the user's stated goals and the approved implementation plan
-3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `gspec-version` YAML frontmatter. If a file lacks frontmatter, add `---\ngspec-version: 1.10.0\n---` at the top.
+3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `spec-version` YAML frontmatter. If a file lacks frontmatter, add `---\nspec-version: v1\n---` at the top.
 4. **Run tests** — Execute the tests defined for this phase (and any existing tests to catch regressions). Fix any failures before proceeding.
 6. **Surface new gaps** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 7. **Pause and report** — After completing the phase and confirming tests pass, present a phase completion summary to the user:
@@ -128,8 +129,8 @@ After implementation:
 1. **Walk through each functional requirement** from the feature PRD (if available) or the approved implementation plan and confirm it's satisfied
 2. **Review against acceptance criteria** — For each capability in the feature PRDs, check that every acceptance criterion listed under it is satisfied. These sub-listed conditions are the definition of "done" for each capability. If any criterion is not met, the capability should not be marked `[x]`.
 3. **Check the Definition of Done** from `gspec/practices.md`
-4. **Note any deferred items** — Requirements that were intentionally postponed or descoped during implementation
-5. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were intentionally deferred. Present a final status summary:
+4. **Verify no unapproved deferrals** — Compare the final implementation against the approved plan. If any capability that was assigned to a phase was not implemented, **do not silently leave it unchecked**. Flag it to the user, explain why it wasn't completed, and get explicit approval before marking it as deferred. Only capabilities the user approved for deferral during planning (or explicitly approves now) may remain unchecked.
+5. **Verify checkbox accuracy** — Confirm that every capability marked `[x]` in the feature PRDs is genuinely implemented and working. Confirm that capabilities left as `[ ]` were approved for deferral by the user. Present a final status summary:
 
 > **Implementation Summary:**
 > - Feature X: 7/7 capabilities implemented (complete)
@@ -148,6 +149,7 @@ When you encounter something the specs don't fully cover during implementation:
 - **If the ambiguity is significant** (e.g., unclear user flow, missing data model, conflicting requirements), pause and consult the user rather than making silent assumptions
 - **Never silently implement unspecified behavior** that contradicts or significantly extends the original spec — ask first
 - **Never override explicit spec decisions** with your own preferences
+- **Never skip or descope a PRD capability without user approval** — ambiguity in *how* to implement something is not grounds for dropping it. If a capability seems too complex, unclear, or problematic, raise it with the user rather than omitting it
 
 ---
 
@@ -177,7 +179,7 @@ If the user specifies a feature, focus on that feature's **unchecked capabilitie
 
 ### When the user provides a prompt alongside existing features:
 
-The user's prompt takes priority for scoping. Use it to determine focus, and reference existing feature PRDs as supporting context rather than the sole driver.
+The user's prompt takes priority for scoping. Use it to determine focus, and reference existing feature PRDs as supporting context rather than the sole driver. However, if the user's prompt narrows scope such that some unchecked PRD capabilities will not be implemented this run, explicitly list those excluded capabilities in the plan under "Out of Scope for This Run" so the user can see what is being deferred and why.
 
 ---
 

package/dist/cursor/gspec-migrate.mdc

@@ -4,7 +4,7 @@ description: Migrate existing gspec files to the current format when upgrading t
 
 You are a Technical Documentation Migration Specialist.
 
-Your task is to update existing gspec specification documents to match the current gspec format (version 1.10.0). You preserve all substantive content while ensuring documents follow the latest structural conventions.
+Your task is to update existing gspec specification documents to match the current spec format (spec-version v1). You preserve all substantive content while ensuring documents follow the latest structural conventions.
 
 ---
 
@@ -18,16 +18,17 @@ Scan the `gspec/` directory for all Markdown files:
 
 
 For each file, check the YAML frontmatter at the top of the file:
-- If the file starts with `---` followed by YAML content and another `---`, read the `gspec-version` field
+- If the file starts with `---` followed by YAML content and another `---`, read the `spec-version` field (also check for the legacy `gspec-version` field)
 - If no frontmatter exists, the file predates version tracking
-- If `gspec-version` matches `1.10.0`, the file is current — skip it
+- If `spec-version` matches `v1`, the file is current — skip it
+- If the file has `gspec-version` (old field name) instead of `spec-version`, it needs migration regardless of value
 
 Present an inventory to the user:
 
 > **gspec File Inventory:**
 > - `gspec/profile.md` — no version (needs migration)
-> - `gspec/stack.md` — version 1.0.3 (needs migration)
-> - `gspec/style.md` — version 1.10.0 (current, skipping)
+> - `gspec/stack.md` — gspec-version 1.0.3 (needs migration — old field name)
+> - `gspec/style.md` — spec-version v1 (current, skipping)
 > - `gspec/features/user-auth.md` — no version (needs migration)
 
 Ask the user to confirm which files to migrate, or confirm all.
@@ -62,21 +63,22 @@ For each file to migrate:
 5. **Add or update the frontmatter** — Ensure the file starts with:
    ```
    ---
-   gspec-version: 1.10.0
+   spec-version: v1
    ---
    ```
+   If the file has the old `gspec-version` field, rename it to `spec-version` and set the value to `v1`.
 6. **Present the proposed changes** to the user before writing. Show what sections are being reorganized, what is being added, and confirm no content is being lost.
 
 ### Phase 4: Verify — Confirm Migration
 
 After migrating all files:
 
-1. **Verify every migrated file** has the correct frontmatter
+1. **Verify every migrated file** has the correct frontmatter (`spec-version: v1`)
 2. **Verify no content was lost** — Briefly summarize what was preserved and any content that was relocated
 3. **Present a completion summary**:
 
 > **Migration Complete:**
-> - 4 files migrated to version 1.10.0
+> - 4 files migrated to spec-version v1
 > - 2 files were already current (skipped)
 > - Content preserved in all files
 > - Sections reorganized: [list any structural changes]
@@ -99,8 +101,9 @@ After migrating all files:
 
 **Frontmatter handling:**
 - If the file has no frontmatter, add it at the very top
-- If the file has frontmatter without `gspec-version`, add the field
-- If the file has an outdated `gspec-version`, update it
+- If the file has the old `gspec-version` field, rename it to `spec-version`
+- If the file has frontmatter without `spec-version`, add the field
+- If the file has an outdated `spec-version`, update it
 - Preserve any other frontmatter fields that may exist
 
 ---

package/dist/cursor/gspec-practices.mdc

@@ -21,10 +21,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/practices.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/cursor/gspec-profile.mdc

@@ -21,10 +21,10 @@ You should:
 
 - Output **ONLY** a single Markdown document
 - Save the file as `gspec/profile.md` in the root of the project, create the `gspec` folder if it doesn't exist
-- Begin the file with YAML frontmatter containing the gspec version:
+- Begin the file with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/cursor/gspec-research.mdc

@@ -161,7 +161,7 @@ After writing `gspec/research.md`, ask the user:
    - Assumptions & Risks (assumptions, open questions, key risks and mitigations)
    - Success Metrics
    - Implementation Context (standard portability note)
-   - Begin the file with YAML frontmatter: `---\ngspec-version: 1.10.0\n---`
+   - Begin the file with YAML frontmatter: `---\nspec-version: v1\n---`
 2. **Name the file** descriptively based on the feature (e.g., `gspec/features/csv-export.md`, `gspec/features/onboarding-wizard.md`)
 3. **Keep the PRD portable** — use generic role descriptions (not project-specific persona names), define success metrics in terms of the feature's own outcomes (not project-level KPIs), and describe UX behavior generically (not tied to a specific design system). The PRD should be reusable across projects.
 4. **Keep the PRD product-focused** — describe *what* and *why*, not *how*. Implementation details belong in the code, not the PRD.
@@ -177,10 +177,10 @@ After writing `gspec/research.md`, ask the user:
 
 - Save the primary output as `gspec/research.md` in the root of the project, create the `gspec` folder if it doesn't exist
 - If the user accepts feature generation (Phase 7), also save feature PRDs to `gspec/features/`
-- Begin `gspec/research.md` with YAML frontmatter containing the gspec version:
+- Begin `gspec/research.md` with YAML frontmatter containing the spec version:
   ```
   ---
-  gspec-version: 1.10.0
+  spec-version: v1
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -197,7 +197,7 @@ The `gspec/research.md` file must follow this structure:
 
 ```markdown
 ---
-gspec-version: 1.10.0
+spec-version: v1
 ---
 
 # Competitive Research