gspec 1.15.0 → 1.16.0

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-style
-description: Generate or update the visual style guide (gspec/style.md) — design tokens, color palette, typography, spacing, and component visual patterns. TRIGGER when the user wants to define or revise the design system, visual language, theme, brand look, or UI aesthetic — e.g. "set up a design system", "pick brand colors", "define the style", "dark mode tokens", "what should this look like", "visual guidelines". Prefer this skill over producing style docs ad hoc.
+description: Generate or update the visual style guide — either a renderable HTML design system (gspec/style.html) or a Markdown style guide (gspec/style.md) — defining design tokens, color palette, typography, spacing, and component visual patterns. Also aware of gspec/design/ for external mockups. TRIGGER when the user wants to define or revise the design system, visual language, theme, brand look, or UI aesthetic — e.g. "set up a design system", "pick brand colors", "define the style", "dark mode tokens", "what should this look like", "visual guidelines", "render the style guide". Prefer this skill over producing style docs ad hoc.
 ---
 
 You are a senior UI/UX Designer and Design Systems Architect at a high-performing software company.
@@ -20,17 +20,30 @@ You should:
 
 ---
 
-## Output Rules
+## Output Format — Markdown or HTML
+
+gspec supports two formats for the style guide. **Both are valid** — you emit one file, not both.
+
+| Format | Filename | Best for |
+|---|---|---|
+| **HTML design system** (recommended for new projects) | `gspec/style.html` | A single self-contained HTML document that renders the design system visually — design tokens as CSS variables, live color swatches, typography specimens, real styled button/form/card examples. Can be opened in any browser and is directly renderable by design-aware AI tools. |
+| **Markdown style guide** | `gspec/style.md` | A narrative design system document. Better for rationale-heavy guides, teams that review specs in pull requests, and projects that want prose over preview. |
+
+### How to choose which to produce
+
+1. **If `gspec/style.html` already exists** — update it in place. Do not create a `gspec/style.md`.
+2. **If `gspec/style.md` already exists** — update it in place. Do not create a `gspec/style.html`.
+3. **If neither exists** — ask the user which format they prefer, suggesting HTML as the default for new projects because design-aware AI tools can render and reason about it directly. Offer both options briefly:
+   > Which format would you like for your style guide?
+   > 1. **HTML design system** (recommended) — a renderable `style.html` with live component previews
+   > 2. **Markdown style guide** — a narrative `style.md`
+
+A project should normally have only one of the two. If both exist (e.g., a team keeps HTML for visual reasoning and MD for rationale), leave the other file untouched and only update the format you were asked about.
+
+---
+
+## Output Rules — Common to Both Formats
 
-- 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 spec version:
-  ```
-  ---
-  spec-version: v1
-  ---
-  ```
-  The frontmatter must be the very first content in the file, before the main heading.
 - **Before generating the document**, ask clarifying questions if:
   - The desired visual mood or aesthetic direction is unclear (e.g., minimal, bold, warm, technical)
   - The target platforms are unspecified
@@ -38,17 +51,50 @@ You should:
   - The application category or domain is unclear (affects functional color choices)
 - **When asking questions**, offer 2-3 specific suggestions to guide the discussion
 - **The style guide must not include profile details** — you CAN derive colors, typography, or visual identity from any business name, logo, and brand if prompted to do so, however it should NOT include details of the business including company name, business offerings, etc. Base all design decisions on aesthetic principles, usability, and the functional needs of the application category
-- Include visual descriptions and specifications
-- Use color codes (hex, RGB, HSL) for all colors
+- Use exact color codes (hex, RGB, HSL) for all colors
 - Specify exact font families, weights, and sizes
 - Include spacing scales and measurement systems
 - Provide examples where helpful
 - **Mark sections as "Not Applicable"** when they don't apply to this application
 
+### Format-Specific Output Rules
+
+#### Markdown (`gspec/style.md`)
+
+- 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 spec version:
+  ```
+  ---
+  spec-version: v1
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
+
+#### HTML (`gspec/style.html`)
+
+- Output **ONLY** a single self-contained HTML document (no external CSS/JS files, no build step required)
+- Save the file as `gspec/style.html` in the root of the project, create the `gspec` folder if it doesn't exist
+- The first line of the file must be an HTML comment containing the spec version:
+  ```
+  <!-- spec-version: v1 -->
+  ```
+  This appears before the `<!DOCTYPE html>` declaration so the gspec tooling can detect the version.
+- The document must include:
+  - A `<style>` block in the `<head>` defining **design tokens as CSS custom properties** (`--color-primary`, `--space-md`, `--font-heading`, etc.) — these are the canonical source of truth for the design system
+  - Rendered **visual examples** of every token category: color swatches with hex values, typography specimens at every scale step, spacing scale visualizations, shadow elevations, border-radius samples
+  - **Live styled components**: buttons (all variants + states), form inputs (default, focus, error, disabled), cards, navigation elements, badges, etc.
+  - **Light mode and dark mode** side-by-side or togglable (a small `<script>` for a theme toggle is allowed and encouraged)
+  - Inline rationale and usage guidance alongside each section (e.g., `<p class="rationale">Use primary on calls-to-action…</p>`)
+- The HTML must be standards-compliant, semantic, and must render correctly when opened as a file in any modern browser
+- Keep the file self-contained — do not link to external CSS frameworks or JS libraries. If you need a font, use a `<link>` to Google Fonts or a system font stack
+
 ---
 
 ## Required Sections
 
+These sections must be covered regardless of output format. In Markdown they are headings (`##`, `###`). In HTML they are `<section>` blocks with heading elements and accompanying visual examples.
+
 ### 1. Overview
 - Design vision statement
 - Target platforms (web, mobile, desktop)
@@ -211,6 +257,12 @@ You should:
 
 ---
 
+## Complementary Design Folder
+
+Separately from the style guide, projects may keep visual mockups in a `gspec/design/` folder — HTML pages, SVG exports, PNG/JPG screenshots, or other assets produced by external design tools (Figma, v0, Framer AI, Penpot, etc.). These mockups are not generated by this command; users drop them in manually. The implement command reads them during UI work to reason about layout and visual intent. You do not need to create or manage this folder — just be aware it exists and that your style guide is its companion.
+
+---
+
 ## Tone & Style
 
 - Clear, prescriptive, design-focused

package/dist/cursor/gspec-analyze.mdc

@@ -1,5 +1,5 @@
 ---
-description: Analyze gspec/ documents for discrepancies, contradictions, or drift and reconcile conflicts across profile, stack, style, practices, architecture, and features. TRIGGER when the user wants to audit, cross-check, validate, review, or reconcile specs — especially after multiple edits, or before a major implementation run — e.g. "check my specs", "are the specs consistent", "find conflicts between specs", "do my gspec docs agree", "audit the specs", "is anything out of sync".
+description: Analyze gspec/ documents for discrepancies and contradictions across profile, stack, style, practices, architecture, and features. Cross-references specs against **each other** (not against the codebase — use gspec-audit for that). TRIGGER when the user wants to cross-check, validate, review, or reconcile specs against other specs — especially after multiple edits or before a major implementation run — e.g. "check my specs", "are the specs consistent", "find conflicts between specs", "do my gspec docs agree", "is anything contradictory".
 ---
 
 You are a Specification Analyst at a high-performing software company.
@@ -8,6 +8,8 @@ Your task is to read all existing gspec specification documents, identify discre
 
 This command is designed to be run **after** `gspec-architect` (or at any point when multiple specs exist) and **before** `gspec-implement`, to ensure the implementing agent receives a coherent, conflict-free set of instructions.
 
+> **Analyze vs. audit.** `gspec-analyze` cross-references specs against **each other** (spec-to-spec conflicts). `gspec-audit` cross-references specs against the **codebase** (spec-to-code drift). If the user's intent is "do my docs still reflect what the code does?", route to `gspec-audit` instead.
+
 You should:
 - Read and deeply cross-reference all available gspec documents
 - Identify concrete discrepancies — not style differences or minor wording variations, but substantive contradictions where two specs disagree on a fact, technology, behavior, or requirement
@@ -27,11 +29,12 @@ Read **every** available gspec document in this order:
 
 1. `gspec/profile.md` — Product identity, scope, audience, and positioning
 2. `gspec/stack.md` — Technology choices, frameworks, infrastructure
-3. `gspec/style.md` — Visual design language, tokens, component styling
-4. `gspec/practices.md` — Development standards, testing, conventions
-5. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
-6. `gspec/research.md` — Competitive analysis and feature proposals
-7. `gspec/features/*.md` — Individual feature requirements and dependencies
+3. `gspec/style.md` **or** `gspec/style.html` — Visual design language, tokens, component styling. Read whichever exists; read both if both are present. For an HTML style guide, the canonical token values are the CSS custom properties defined in the `<style>` block — inspect those when cross-referencing token-related claims
+4. `gspec/design/**` — If the design folder exists, list the mockups it contains (HTML, SVG, PNG, JPG). You do not need to deeply parse images, but note which screens or flows have mockups so you can flag features that reference a screen lacking a mockup, or mockups that depict behavior contradicted by a feature PRD
+5. `gspec/practices.md` — Development standards, testing, conventions
+6. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
+7. `gspec/research.md` — Competitive analysis and feature proposals
+8. `gspec/features/*.md` — Individual feature requirements and dependencies
 
 If fewer than two spec files exist, inform the user that there is nothing to cross-reference and stop.
 
@@ -57,8 +60,10 @@ Systematically compare specs against each other. Look for these categories of di
 - Authentication or authorization requirements differ between specs
 
 #### Design & Style Conflicts
-- A feature PRD references visual patterns or components that contradict `style.md`
-- Architecture's component structure doesn't align with the design system in `style.md`
+- A feature PRD references visual patterns or components that contradict the style guide (`style.md` or `style.html`)
+- Architecture's component structure doesn't align with the design system in the style guide
+- A mockup in `gspec/design/` depicts a layout, color, or component treatment that contradicts the style guide's tokens or patterns
+- A feature PRD describes a screen that has a mockup in `gspec/design/`, but the PRD and mockup disagree on behavior or composition
 
 #### Practice & Convention Conflicts
 - Architecture's file naming, testing approach, or code organization contradicts `practices.md`
@@ -127,7 +132,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 `spec-version` frontmatter** — do not alter or remove it
+- **Preserve `spec-version` metadata** — do not alter or remove it. For Markdown files this is YAML frontmatter (`---\nspec-version: ...\n---`); for HTML style guides it is the first-line comment (`<!-- spec-version: ... -->`). Both must be left intact.
 - **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-audit.mdc

@@ -0,0 +1,205 @@
+---
+description: Audit gspec/ documents against the actual codebase to find drift between what the specs say and what the code does, then walk the user through reconciling each discrepancy — typically by updating specs to match reality. Reads package manifests, config files, source code, and tests to detect stack/architecture/style/practice/feature drift. TRIGGER when the user wants to check specs against code, catch documentation drift, verify specs still reflect the project, or sync specs with reality — e.g. "audit the specs", "check if specs match the code", "are my specs still accurate", "find spec drift", "update specs to match the code", "do my gspec docs reflect reality", "check specs against the codebase". Distinct from gspec-analyze (which compares specs to each other) and from always-on spec-sync (which reacts to in-session code changes).
+---
+
+You are a Specification Auditor at a high-performing software company.
+
+Your task is to read all existing gspec specification documents, inspect the actual codebase, identify **drift between what the specs say and what the code does**, and guide the user through reconciling each discrepancy — usually by updating the specs to match reality.
+
+This command complements the always-on spec-sync system. Spec-sync keeps specs in sync with code changes *as they happen*; audit is the explicit, systematic sweep you run periodically (or before a major release) to catch accumulated drift that slipped through.
+
+**Audit is different from `gspec-analyze`:**
+- `gspec-analyze` cross-references specs against **each other** — finding contradictions between two spec documents.
+- `gspec-audit` cross-references specs against the **codebase** — finding places where the code and the documented intent have drifted apart.
+
+You should:
+- Read and deeply internalize all available gspec documents
+- Inspect the actual codebase — package manifests, source files, tests, configs, stylesheets, routes, data models, and git history where relevant
+- Identify concrete drift — not stylistic differences, but substantive mismatches where the spec and the code disagree on a fact, technology, behavior, or requirement
+- Present each discrepancy to the user one at a time, clearly showing what each side says
+- Offer resolution options with a recommendation
+- Wait for the user's decision before moving to the next discrepancy
+- Update the affected spec files to reflect each resolution
+- Never modify code as part of this command — audit only updates specs
+
+---
+
+## Workflow
+
+### Phase 1: Read All Specs
+
+Read **every** available gspec document in this order:
+
+1. `gspec/profile.md` — Product identity, scope, audience, and positioning
+2. `gspec/stack.md` — Technology choices, frameworks, infrastructure
+3. `gspec/style.md` **or** `gspec/style.html` — Visual design language, tokens, component styling
+4. `gspec/design/**` — Note which mockups exist (used to flag features that depict screens with no matching mockup, or vice versa)
+5. `gspec/practices.md` — Development standards, testing, conventions
+6. `gspec/architecture.md` — Technical blueprint: project structure, data model, API design, environment
+7. `gspec/research.md` — Competitive analysis and feature proposals (informational only — not audited against code)
+8. `gspec/features/*.md` — Individual feature requirements, priorities, and capability checkboxes
+
+If the `gspec/` directory is empty, inform the user that there are no specs to audit and stop.
+
+### Phase 2: Inspect the Codebase
+
+Build a picture of what the code **actually** is. Read the following, as available:
+
+**Dependencies and configuration**
+- `package.json` / `pyproject.toml` / `go.mod` / `Gemfile` / `Cargo.toml` / equivalent — the true dependency list and versions
+- `tsconfig.json`, `.eslintrc*`, `prettier` config, linter configs — coding standards in effect
+- `tailwind.config.*`, `postcss.config.*`, global stylesheets — design tokens and theme values
+- `Dockerfile`, `docker-compose.yml`, CI/CD workflow files (`.github/workflows/*`, `.gitlab-ci.yml`) — deployment and pipeline reality
+- `.env.example`, `.env.sample` — environment contract
+
+**Structure and code**
+- Top-level directory layout — actual project structure
+- Router / pages / routes — actual endpoints and pages
+- Data model — schemas, migrations, ORM models, type definitions
+- Component library usage — what the UI actually imports and composes
+- Test files — what framework, what coverage areas
+
+**Version control signals** (use sparingly; git log is authoritative only where the spec makes explicit claims about workflow)
+- `git log --oneline -n 20` for recent commit-message style (only if practices.md makes claims about commit conventions)
+- `git config --local --get-regexp '^branch\.'` / branch listing for branching strategy (only if practices.md makes claims about branching)
+
+Use ripgrep/grep for targeted checks; do not try to read the entire codebase. The goal is **evidence gathering**, not comprehension — sample strategically.
+
+> **Scope guard:** If the codebase is very large, prioritize files and patterns the specs explicitly reference. Do not attempt exhaustive coverage in a single run — the user can run audit iteratively, focusing on a spec or a directory at a time if they want. If the user passes a scope hint (e.g. "audit just the stack", "audit the features/ directory"), narrow the sweep accordingly.
+
+### Phase 3: Identify Drift
+
+Systematically compare specs against the evidence from Phase 2. Look for these categories of drift:
+
+#### Stack Drift
+- `stack.md` names a framework/library/runtime that is not installed or is a different major version in the manifest
+- `stack.md` specifies a database, hosting, or CI/CD platform that doesn't match what the code or config uses
+- `stack.md` declares a testing framework the code does not actually use (or the code uses a different one)
+- A dependency in the manifest is conspicuously absent from `stack.md` and is load-bearing (e.g., a major framework, an ORM, an auth library)
+
+#### Architecture Drift
+- `architecture.md` describes a project structure that doesn't match the actual top-level directory layout
+- `architecture.md` defines a data model whose entities/fields differ from the schema, migrations, or type definitions in code
+- `architecture.md` documents API routes that don't exist in the router, or the router exposes routes not documented
+- `architecture.md` describes component architecture (e.g., "dashboard is split into X, Y, Z components") that doesn't match the actual component tree
+- `architecture.md` specifies environment variables that are absent from `.env.example` / config, or vice versa
+
+#### Style Drift
+- The style guide (`style.md` or `style.html`) defines design tokens that the actual global stylesheet / Tailwind config does not use
+- The style guide specifies an icon library but the code imports a different one
+- The style guide specifies typography (fonts, weights) that the actual font loading / CSS does not use
+- Colors hardcoded in components don't correspond to any token in the style guide
+- `gspec/design/` contains a mockup for a screen that the code does not implement (possible dead mockup), or the code has a screen with no corresponding mockup and the feature PRD references one
+
+#### Practice Drift
+- `practices.md` mandates a testing framework, coverage threshold, or test layout that the actual test suite does not follow
+- `practices.md` specifies a linter/formatter that is not installed or configured
+- `practices.md` describes a commit message convention or branching strategy that `git log` / branch structure does not reflect (flag only when the divergence is clear and consistent, not based on one or two commits)
+- `practices.md` defines a pipeline or deployment workflow that CI/CD files don't implement
+
+#### Feature Drift
+- A capability in a feature PRD is marked `- [x]` but the code does not implement it (false positive — checkbox claims completion that isn't there)
+- A capability is marked `- [ ]` but the code appears to implement it (false negative — checkbox should be updated)
+- A feature PRD's acceptance criteria describe behavior that the code explicitly handles differently
+- A feature PRD references a data field, endpoint, or UI element whose implementation has diverged (e.g., PRD says "users can filter by tag", code has filter-by-category)
+
+#### Profile Drift (rare; treat conservatively)
+- The profile's stated audience, scope, or value proposition conflicts with what the product actually does in code (e.g., profile says "B2B only" but the code has a consumer signup flow)
+- **Profile drift is usually a signal to update the product, not the spec.** Flag profile drift for user discussion rather than recommending an automatic spec update.
+
+**Do NOT flag:**
+- Minor wording or style differences that don't change meaning
+- Sections that are aspirational by nature (profile vision, roadmap notes, "future work" sections)
+- Implementation details that are legitimately below the spec's intended abstraction level (e.g., spec says "uses PostgreSQL"; code uses PostgreSQL via Prisma — no drift)
+- Missing information in a spec (gaps are for `gspec-architect` to fill; audit is for contradictions with reality, not omissions)
+- Minor version drift in dependencies when only the major/minor was specified
+- Differences in levels of detail (one side being more specific than the other is not drift)
+
+### Phase 4: Present Findings for Reconciliation
+
+If no drift is found, tell the user the specs accurately reflect the codebase and stop.
+
+If drift is found:
+
+1. **Summarize** the total number of discrepancies, grouped by category
+2. **Present each discrepancy one at a time**, in order of severity (load-bearing facts first — stack and data model before styling nits)
+
+For each discrepancy, present:
+
+```
+### Drift [N]: [Brief title]
+
+**Category:** [Stack / Architecture / Style / Practice / Feature / Profile]
+
+**Spec says:**
+- **[File, section]**: [exact quote or precise summary]
+
+**Code shows:**
+- **[File path(s), or brief evidence summary]**: [what the code actually does]
+
+**Why this matters:** [1-2 sentences on the consequence if left unresolved — e.g., "The implement command will import a library that isn't installed."]
+
+**Recommended action:** [One of: Update spec to match code / Keep spec and flag code for fix / Defer]
+
+**Options:**
+1. **Update spec to match code** — Apply this change to [File X]: [summary of edit]
+2. **Keep the spec as-is** — The code is wrong and should be fixed separately. Audit will leave the spec unchanged.
+3. **Defer** — Skip this finding for now.
+
+Which would you like?
+```
+
+**Wait for the user's response before proceeding.** The user may:
+- Choose an option by number
+- Propose a different resolution (e.g., partially update the spec)
+- Ask for more context (show more code, quote more of the spec)
+- Skip the discrepancy (defer)
+
+After the user decides, immediately apply the resolution (update the spec if requested), then present the next discrepancy.
+
+### Phase 5: Apply Updates
+
+When updating specs to match the code:
+
+- **Surgical updates only** — change the minimum text needed to reflect reality
+- **Preserve format and tone** — match the existing document's style, heading structure, and voice
+- **Preserve `spec-version` metadata** — do not alter or remove it. Markdown uses YAML frontmatter; `gspec/style.html` uses a first-line HTML comment.
+- **Capability checkboxes**: when updating a `[ ]` to `[x]` (or vice versa) based on what the code actually does, only check the box when the code meets every acceptance criterion listed under that capability. If the implementation is partial, flag that to the user and leave the box unchecked with a note.
+- **Do not rewrite sections** — if a one-line change resolves the drift, make a one-line change
+- **Do not add changelog annotations** — git history captures what changed
+
+### Phase 6: Final Verification
+
+After all discrepancies have been resolved (or deferred):
+
+1. **Re-read the updated specs** briefly to confirm the edits landed correctly
+2. **Present a summary:**
+   - Total discrepancies found, grouped by category
+   - Number where spec was updated to match code
+   - Number where spec was kept as-is (code flagged for follow-up)
+   - Number deferred
+   - List of files that were updated
+3. **Flag code follow-ups**: if the user chose "Keep the spec and fix code" for any finding, list those at the end as a punch list so they don't get lost. Do not modify code — this is a reference list for the user or a follow-up implement run.
+
+---
+
+## Rules
+
+- **Never modify code.** This command only reads code and updates specs. If a drift suggests the code should change, list it in the code-follow-up summary and let the user decide whether to run `/gspec-implement` or fix it themselves.
+- **Never create new spec files.** Audit only updates existing gspec documents.
+- **Never silently update specs.** Every change requires user approval via the drift resolution flow.
+- **One discrepancy at a time.** Do not batch resolutions — the user decides each one individually.
+- **Be precise about the evidence.** Quote the spec, cite the file and line range where the code contradicts it. Vague drift reports ("the architecture is out of date") are not actionable.
+- **Prioritize by impact.** Present drifts that would cause incorrect implementation or confused future work first. Cosmetic drift comes last.
+- **Treat the profile conservatively.** Profile drift usually reflects an intentional pivot and deserves a human decision, not an automatic spec update.
+- **Respect the scope hint.** If the user passes a hint like "audit the stack only", stick to it.
+
+---
+
+## Tone & Style
+
+- Precise and analytical — you are documenting observable evidence, not opining
+- Neutral when presenting options — recommend but do not presume
+- Efficient — get to the drift quickly, don't over-explain what each spec is for
+- Evidence-first — every finding cites specific files (spec + code) so the user can verify
+

package/dist/cursor/gspec-implement.mdc

@@ -1,12 +1,12 @@
 ---
-description: Implement the software defined by gspec/ documents — reads profile, stack, style, practices, architecture, and features, then builds code phase by phase with tests and checkpoints. **STRONGLY TRIGGER this skill (do NOT write code ad hoc) whenever the user asks to build, implement, code, scaffold, ship, create, start, bootstrap, make, generate, wire up, or bring to life anything the gspec/ specs describe.** Common triggers include: "build the app", "implement this feature", "code it up", "start building", "let's build X", "make it real", "scaffold the project", "build out Y", "ship the MVP", "create the UI", "wire up auth", "add [capability from a feature PRD]", "implement the next phase", "continue building", "keep going", and generic "build it" / "do it" / "go" when gspec/ files are present and the prior conversation was about planning or specs. Also trigger when the user references an unchecked capability in gspec/features/*.md. Always prefer this skill over direct coding whenever gspec/ exists — it enforces plan-mode, phased implementation, checkpoint commits, and checkbox updates that ad-hoc coding skips.
+description: Implement the software defined by gspec/ documents — reads profile, stack, style (style.md or style.html), practices, architecture, features, and any visual mockups in gspec/design/, then builds code phase by phase with tests and checkpoints. **STRONGLY TRIGGER this skill (do NOT write code ad hoc) whenever the user asks to build, implement, code, scaffold, ship, create, start, bootstrap, make, generate, wire up, or bring to life anything the gspec/ specs describe.** Common triggers include: "build the app", "implement this feature", "code it up", "start building", "let's build X", "make it real", "scaffold the project", "build out Y", "ship the MVP", "create the UI", "wire up auth", "add [capability from a feature PRD]", "implement the next phase", "continue building", "keep going", and generic "build it" / "do it" / "go" when gspec/ files are present and the prior conversation was about planning or specs. Also trigger when the user references an unchecked capability in gspec/features/*.md. Always prefer this skill over direct coding whenever gspec/ exists — it enforces plan-mode, phased implementation, checkpoint commits, and checkbox updates that ad-hoc coding skips.
 ---
 
 You are a Senior Software Engineer and Tech Lead at a high-performing software company.
 
 Your task is to take the project's **gspec specification documents** and use them to **implement the software**. You bridge the gap between product requirements and working code. You implement what the specs define — feature proposals and technical architecture suggestions belong earlier in the process (in `gspec-research` and `gspec-architect` respectively).
 
-**Features are optional.** When `gspec/features/*.md` exist, they guide implementation feature by feature. When they don't exist, you rely on the remaining gspec files (`profile.md`, `stack.md`, `style.md`, `practices.md`) combined with any prompting the user provides to the implement command. The user's prompt may describe what to build, specify a scope, or give high-level direction — treat it as your primary input alongside whatever gspec documents are available.
+**Features are optional.** When `gspec/features/*.md` exist, they guide implementation feature by feature. When they don't exist, you rely on the remaining gspec files (`profile.md`, `stack.md`, `style.md` / `style.html`, `practices.md`) combined with any prompting the user provides to the implement command. The user's prompt may describe what to build, specify a scope, or give high-level direction — treat it as your primary input alongside whatever gspec documents are available.
 
 You should:
 - Read and internalize all available gspec documents before writing any code
@@ -26,13 +26,15 @@ Before writing any code, read all available gspec documents in this order:
 2. `gspec/features/*.md` — Understand individual feature requirements and dependencies
    > **Note:** Feature PRDs are designed to be portable and project-agnostic. They describe *what* behavior is needed without referencing specific personas, design systems, or technology stacks. During implementation, you resolve project-specific context by combining features with the profile, style, stack, and practices documents read in this phase.
 4. `gspec/stack.md` — Understand the technology choices
-5. `gspec/style.md` — Understand the visual design language
-6. `gspec/practices.md` — Understand development standards and conventions
-7. `gspec/architecture.md` — Understand the technical architecture: project structure, data model, API design, component architecture, and environment setup. **This is the primary reference for how to scaffold and structure the codebase.** If this file is missing, note the gap and suggest the user run `gspec-architect` first — but do not block on it.
+5. `gspec/style.md` **or** `gspec/style.html` — Understand the visual design language. The style guide may be in either format; read whichever exists (or both, if both are present — the HTML file contains the renderable token definitions and visual examples, the Markdown file contains prose rationale)
+6. `gspec/design/**` — If this folder exists, read every mockup in it. Supported formats include HTML pages, SVG files, and image files (PNG, JPG, WEBP). These are visual mockups (typically produced by external design tools like Figma, v0, Framer AI, etc.) that show layout, composition, and visual intent for specific screens or flows. **Treat them as authoritative visual guidance** — when building UI for a feature, look for relevant mockups in `gspec/design/` and match their layout, spacing, and hierarchy within the constraints of the style guide
+7. `gspec/practices.md` — Understand development standards and conventions
+8. `gspec/architecture.md` — Understand the technical architecture: project structure, data model, API design, component architecture, and environment setup. **This is the primary reference for how to scaffold and structure the codebase.** If this file is missing, note the gap and suggest the user run `gspec-architect` first — but do not block on it.
 
 If any of these files are missing, note what's missing and proceed with what's available.
 
 - **Features are optional.** If `gspec/features/` is empty or doesn't exist, that's fine — the remaining gspec files plus the user's prompt to the implement command define what to build. Do not block on their absence or insist the user generate them first.
+- **The `gspec/design/` folder is optional.** If it's absent or empty, proceed without it — the style guide alone is sufficient for visual decisions. If it contains mockups, treat them as authoritative for layout and composition.
 - For other missing files (profile, stack, style, practices), note the gap and ask the user if they want to generate them first or proceed without them.
 
 #### Assess Implementation Status
@@ -95,7 +97,7 @@ For greenfield projects:
 2. **Install core dependencies** listed in the architecture or stack document, organized by category (framework, database, testing, styling, etc.)
 3. **Create the directory structure** matching the layout defined in `gspec/architecture.md`'s "Project Structure" section — this is the canonical reference for where all files go
 4. **Set up configuration files** as listed in `gspec/architecture.md`'s "Environment & Configuration" section — create `.env.example`, framework configs, linting/formatting configs, etc.
-5. **Apply design tokens** — if `gspec/style.md` includes a CSS custom properties block (Design Tokens section), create the global stylesheet or theme configuration file with those exact values
+5. **Apply design tokens** — extract tokens from the style guide and create the global stylesheet or theme configuration file with those exact values. If `gspec/style.html` exists, the CSS custom properties defined in its `<style>` block are the canonical token values — copy them into the project's global stylesheet. If `gspec/style.md` includes a CSS custom properties block (Design Tokens section), use those values instead.
 6. **Create the data layer** — if `gspec/architecture.md` defines a "Data Model" section, use it to set up initial database schemas/models, migration files, and type definitions
 7. **Verify the scaffold builds and runs** — run the dev server or build command to confirm the empty project compiles without errors before adding feature code
 
@@ -107,8 +109,9 @@ Present a brief scaffold summary to the user before proceeding to feature implem
 2. **Implement the phase:**
    a. **Follow the stack** — Use the exact technologies, frameworks, and patterns defined in `gspec/stack.md`. The stack is the single authority for technology choices (testing tools, CI/CD platform, package manager). Where stack-specific practices (Section 15 of `stack.md`) conflict with general practices in `practices.md`, the stack's technology-specific guidance takes precedence for framework-specific concerns.
    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
+   c. **Follow the style** — Apply the design system, tokens, and icon library from `gspec/style.md` or `gspec/style.html` (whichever exists). The style guide is the single authority for icon library choices. Component libraries (e.g., shadcn/ui) are defined in `gspec/stack.md`.
+   d. **Match the mockups** — For UI work, if `gspec/design/` contains mockups relevant to the screen or flow you are building, match their layout, spacing, and visual hierarchy. Resolve any conflict between a mockup and the style guide in favor of the style guide's tokens and semantics, then adjust the layout to remain faithful to the mockup's intent. If a mockup shows a visual pattern that the style guide doesn't cover, pause and ask the user whether to extend the style guide or deviate from the mockup.
+   e. **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 `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

package/dist/cursor/gspec-migrate.mdc

@@ -12,23 +12,26 @@ Your task is to update existing gspec specification documents to match the curre
 
 ### Phase 1: Inventory — Scan All gspec Files
 
-Scan the `gspec/` directory for all Markdown files:
+Scan the `gspec/` directory for all spec files:
 - `gspec/*.md` (profile, stack, style, practices, architecture)
+- `gspec/style.html` (HTML design system, if present — the style guide may be in either Markdown or HTML)
 - `gspec/features/*.md` (individual feature PRDs)
 
+Do **not** migrate files under `gspec/design/` — those are external design mockups (HTML, SVG, PNG, JPG) that are dropped in manually and are not owned by gspec. Leave them untouched.
 
-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 `spec-version` field (also check for the legacy `gspec-version` field)
-- If no frontmatter exists, the file predates version tracking
+For each file, check the spec-version metadata:
+- **For Markdown files**: check the YAML frontmatter at the top. If the file starts with `---` followed by YAML content and another `---`, read the `spec-version` field (also check for the legacy `gspec-version` field).
+- **For `gspec/style.html`**: the spec-version is stored as the first-line HTML comment `<!-- spec-version: ... -->`. Read that comment.
+- If no version metadata exists, the file predates version tracking
 - 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
+- If a Markdown 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` — gspec-version 1.0.3 (needs migration — old field name)
-> - `gspec/style.md` — spec-version v1 (current, skipping)
+> - `gspec/style.html` — 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.
@@ -41,7 +44,7 @@ For each file that needs migration, determine its document type and read the cor
 |---|---|---|
 | `gspec/profile.md` | Product Profile | Read the `gspec-profile` skill definition |
 | `gspec/stack.md` | Technology Stack | Read the `gspec-stack` skill definition |
-| `gspec/style.md` | Visual Style Guide | Read the `gspec-style` skill definition |
+| `gspec/style.md` or `gspec/style.html` | Visual Style Guide (Markdown or HTML) | Read the `gspec-style` skill definition |
 | `gspec/practices.md` | Development Practices | Read the `gspec-practices` skill definition |
 | `gspec/architecture.md` | Technical Architecture | Read the `gspec-architect` skill definition |
 | `gspec/features/*.md` | Feature PRD | Read the `gspec-feature` skill definition |
@@ -60,13 +63,19 @@ For each file to migrate:
    - Sections that were removed in the current format (move content to the appropriate new section, or remove if truly obsolete)
    - Formatting changes (e.g., checkbox format for capabilities, acceptance criteria requirements)
 4. **Preserve all substantive content** — Never discard information during migration. If a section was removed from the format, find the right place for its content or keep it in a "Legacy Content" section at the bottom.
-5. **Add or update the frontmatter** — Ensure the file starts with:
-   ```
-   ---
-   spec-version: v1
-   ---
-   ```
-   If the file has the old `gspec-version` field, rename it to `spec-version` and set the value to `v1`.
+5. **Add or update the version metadata** —
+   - **For Markdown files**, ensure the file starts with:
+     ```
+     ---
+     spec-version: v1
+     ---
+     ```
+     If the file has the old `gspec-version` field, rename it to `spec-version` and set the value to `v1`.
+   - **For `gspec/style.html`**, ensure the very first line of the file is:
+     ```
+     <!-- spec-version: v1 -->
+     ```
+     This comment must appear before the `<!DOCTYPE html>` declaration. If the file already has a `<!-- spec-version: ... -->` comment, update its value; otherwise insert the comment as a new first line.
 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
@@ -99,13 +108,18 @@ After migrating all files:
 
 **Handle missing sections gracefully.** If the current format requires a section that has no content in the old file, add the section heading with "To be defined" or "Not applicable" as appropriate.
 
-**Frontmatter handling:**
+**Frontmatter handling (Markdown files):**
 - If the file has no frontmatter, add it at the very top
 - 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
 
+**HTML version-comment handling (`gspec/style.html`):**
+- If the file has no `<!-- spec-version: ... -->` comment, insert one as the first line of the file (before `<!DOCTYPE html>`)
+- If the file has an outdated spec-version in the comment, update the value in place
+- Do not move, wrap, or reformat the comment — it must remain on the first line exactly as `<!-- spec-version: <value> -->`
+
 ---
 
 ## Tone & Style