gspec 1.0.3 → 1.1.0

package/dist/cursor/gspec-record.mdc

@@ -29,9 +29,10 @@ Before proposing any updates, read all available gspec documents in this order:
 1. `gspec/profile.md` — Product identity and scope
 2. `gspec/epics/*.md` — Epic structure and feature dependencies
 3. `gspec/features/*.md` — Individual feature requirements
-4. `gspec/stack.md` — Technology choices and architecture
-5. `gspec/style.md` — Visual design system
-6. `gspec/practices.md` — Development standards and conventions
+4. `gspec/stack.md` — Technology choices
+5. `gspec/architecture.md` — Technical architecture: project structure, data model, API design, component architecture, environment setup
+6. `gspec/style.md` — Visual design system
+7. `gspec/practices.md` — Development standards and conventions
 
 If any files are missing, note what is missing and proceed with what is available. You only update specs that exist. Do not create new spec files (profile, stack, style, practices) unless the user explicitly asks. You may create a new feature PRD only when what needs recording constitutes an entirely new feature.
 
@@ -65,10 +66,14 @@ Systematically evaluate which gspec documents need updating. Apply this decision
 |---|---|---|
 | New user-facing capability | `gspec/features/<relevant>.md` | Add capability to existing PRD, or create new PRD if entirely new feature |
 | Modified capability behavior | `gspec/features/<relevant>.md` | Update the affected capability description |
-| Removed or deprecated capability | `gspec/features/<relevant>.md` | Move to Non-Goals or Future Considerations, note deprecation |
+| Removed or deprecated capability | `gspec/features/<relevant>.md` | Move to Scope section (out-of-scope or deferred), note deprecation |
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
+| New data entity or changed data model | `gspec/architecture.md` | Update Data Model section with new/changed entities |
+| New API endpoint or changed route | `gspec/architecture.md` | Update API Design section with new/changed routes |
+| Project structure change (new directory, reorganization) | `gspec/architecture.md` | Update Project Structure section |
+| Environment variable added or changed | `gspec/architecture.md` | Update Environment & Configuration section |
 | Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
 | Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
@@ -115,16 +120,15 @@ After approval, write the spec updates:
 2. **Preserve format** — Match the existing document's style, heading structure, and tone exactly
 3. **Add change context where valuable** — Where appropriate, add a brief parenthetical note indicating the change (e.g., "*(Updated: switched from REST to GraphQL)*"). Do not over-annotate — use judgment about when a note adds value vs. noise.
 4. **For new feature PRDs** — If the change introduces an entirely new feature that warrants its own PRD, follow the same structure used by the `gspec-feature` command:
-   - Overview (name, summary, objective)
-   - Problem & Context
-   - Goals & Non-Goals
+   - Overview (name, summary, problem being solved and why it matters now)
    - Users & Use Cases
-   - Assumptions & Open Questions
-   - Capabilities (with P0/P1/P2 priority levels)
+   - Scope (in-scope goals, out-of-scope items, deferred ideas)
+   - Capabilities (with P0/P1/P2 priority levels, each with 2-4 **acceptance criteria** as a sub-list)
+   - Dependencies (on other features or external services)
+   - Assumptions & Risks (assumptions, open questions, key risks and mitigations — note in assumptions that this feature was recorded during iterative development)
    - Success Metrics
-   - Risks & Mitigations
-   - Future Considerations
-   - Note in the Assumptions section that this feature was recorded during iterative development
+   - Begin the file with YAML frontmatter: `---\ngspec-version: 1.1.0\n---`
+   - **Also update `gspec/architecture.md`** if the new feature introduces data entities, API endpoints, or new components — add them to the appropriate architecture sections
 
 ### Phase 6: Verify — Confirm Consistency
 
@@ -152,6 +156,8 @@ After writing spec updates:
 
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
+**Version frontmatter.** When updating existing gspec files, preserve the `gspec-version` YAML frontmatter at the top of the file. If a file lacks frontmatter, add `---\ngspec-version: 1.1.0\n---` as the very first content before the main heading.
+
 **No code changes.** This command never creates, modifies, or deletes code files. If the user needs code changes alongside spec updates, suggest using `gspec-dor` instead.
 
 ---

package/dist/cursor/gspec-stack.mdc

@@ -21,6 +21,13 @@ 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:
+  ```
+  ---
+  gspec-version: 1.1.0
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
 - **Before generating the document**, ask clarifying questions if:
   - The project type is unclear (web app, mobile, API, CLI, etc.)
   - Scale requirements are not specified

package/dist/cursor/gspec-style.mdc

@@ -21,6 +21,13 @@ 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:
+  ```
+  ---
+  gspec-version: 1.1.0
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
 - **Before generating the document**, ask clarifying questions if:
   - The brand personality or visual direction is unclear
   - Existing brand assets or guidelines are not mentioned (logos, colors, fonts)
@@ -200,9 +207,37 @@ You should:
 ### 12. Design Tokens
 
 #### Token Structure
-- Naming conventions
-- Token categories
-- Example token definitions (CSS variables, JSON, etc.)
+- Naming conventions (e.g., `--color-primary-500`, `--spacing-md`, `--font-size-lg`)
+- Token categories (color, typography, spacing, shadow, border-radius, animation)
+
+#### Token Definitions
+- **Output a complete, machine-parseable token map** as a CSS custom properties code block that the implementing agent can copy directly into the codebase. This is the single source of truth for all design values — every color, spacing value, font size, shadow, and radius defined in earlier sections must appear here as a named token.
+- Example format:
+  ```css
+  :root {
+    /* Colors — Primary */
+    --color-primary-50: #eff6ff;
+    --color-primary-500: #3b82f6;
+    --color-primary-900: #1e3a5f;
+    /* Colors — Semantic */
+    --color-success: #22c55e;
+    --color-error: #ef4444;
+    /* Typography */
+    --font-family-heading: 'Inter', sans-serif;
+    --font-size-h1: 2.25rem;
+    --font-weight-bold: 700;
+    /* Spacing */
+    --spacing-xs: 0.25rem;
+    --spacing-sm: 0.5rem;
+    --spacing-md: 1rem;
+    /* Shadows */
+    --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+    /* Border Radius */
+    --radius-md: 0.375rem;
+  }
+  ```
+- If the project uses a utility-first CSS framework (check `gspec/stack.md` if it exists), also provide the framework-specific configuration (e.g., Tailwind `theme.extend` values) that maps to these tokens
+- For dark mode, provide the overridden token values under a separate selector or media query
 
 ### 13. Usage Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gspec",
-    "version": "1.0.3",
+    "version": "1.1.0",
     "description": "Install gspec specification commands for Claude Code, Cursor, and other AI tools",
     "main": "bin/gspec.js",
     "type": "module",