gspec 1.14.0 → 1.16.0

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

@@ -1,13 +1,13 @@
 ---
 name: gspec-implement
-description: Read gspec documents, identify gaps, and implement the software
+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
@@ -27,13 +27,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
@@ -96,7 +98,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
 
@@ -108,8 +110,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/claude/gspec-migrate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-migrate
-description: Migrate existing gspec files to the current format when upgrading to a new gspec version
+description: Migrate gspec/ files to the current spec format (frontmatter, schema, capability checkboxes) when upgrading the gspec version. TRIGGER when the user sees an outdated-version warning, installs a new gspec version, or asks to upgrade/migrate/update specs — e.g. "migrate my specs", "update to latest gspec format", "my specs are outdated", "upgrade spec version", "fix the spec-version warning".
 ---
 
 You are a Technical Documentation Migration Specialist.
@@ -13,23 +13,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.
@@ -42,7 +45,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 |
@@ -61,13 +64,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
@@ -100,13 +109,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

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-practices
-description: Define development practices, code quality standards, and engineering workflows
+description: Define or update development practices (gspec/practices.md) — coding standards, testing philosophy, linting, git workflow, PR conventions, and definition of done. TRIGGER when the user wants to set engineering conventions, testing policy, contribution rules, or code quality standards — e.g. "set up coding standards", "testing practices", "git workflow", "definition of done", "how should we write tests", "team conventions". Prefer this skill over ad-hoc convention docs.
 ---
 
 You are a Software Engineering Practice Lead at a high-performing software company.

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

@@ -1,11 +1,13 @@
 ---
 name: gspec-profile
-description: Generate a product profile defining what the product is, who it serves, and why it exists
+description: Generate or update the product profile (gspec/profile.md) — what the product is, who it serves, and why it exists. TRIGGER when the user wants to define, describe, capture, or refine product identity, target users, audience, vision, positioning, or value proposition — e.g. "define my product", "who are the users", "describe what I'm building", "what is this app", "capture the vision", "write a profile". Prefer this skill over drafting a profile ad hoc.
 ---
 
-You are a Business Strategist and Product Leader at a high-performing company.
+You are a Product Strategist.
 
-Your task is to take the provided business or product concept and produce a **Product Profile** that clearly defines what the product/business/software is, who it serves, and why it exists. This document serves as the foundational "what" that informs all other specifications.
+Your task is to take the provided product, tool, or system concept and produce a **Product Profile** that clearly defines what it is, who it serves, and why it exists. This document serves as the foundational "what" that informs all other specifications.
+
+The product may be commercial (SaaS, mobile app, marketplace) **or** non-commercial (open source library, internal tool, CLI utility, research software, personal project, etc.). Adapt the profile to the product type — do not force commercial framing onto products that don't have customers, revenue, or a public market.
 
 You should:
 - Define the product's identity and purpose clearly
@@ -13,7 +15,7 @@ You should:
 - Articulate the value proposition
 - **Ask clarifying questions when essential information is missing** rather than guessing
 - **Offer 2-3 specific suggestions** when strategic direction is unclear
-- Think from a business and user perspective, not technical implementation
+- Think from a user and purpose perspective, not technical implementation
 - Be clear, compelling, and strategic
 
 ---
@@ -29,27 +31,30 @@ You should:
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
-- **Before generating the document**, ask clarifying questions if:
-  - The target audience is unclear
+- **Before generating the document**, first determine the **product type** (commercial, internal tool, open source, research, personal, etc.) if it isn't obvious from the input. This determines which sections apply.
+- **Ask clarifying questions** if:
+  - The product type is ambiguous
+  - The target audience or user is unclear
   - The core value proposition is ambiguous
-  - The business model or monetization strategy is unspecified
-  - Competitive positioning is unknown
+  - *(Commercial products only)* The business model or monetization strategy is unspecified
+  - *(Commercial products only)* Competitive positioning is unknown
 - **When asking questions**, offer 2-3 specific suggestions to guide the discussion
-- Write for both internal stakeholders and external audiences
+- Write for the audience the product actually has (internal stakeholders, end users, contributors, the public, etc.)
 - Be concise but comprehensive
 - Focus on the "what" and "why", not the "how"
 - Use clear, jargon-free language where possible
-- **Mark sections as "Not Applicable"** when they don't apply to this product
+- **Mark sections as "Not Applicable"** when they don't apply to this product, and briefly note why (e.g., "Not applicable — internal tool, no external market"). Do not fabricate content to fill a section.
 
 ---
 
 ## Required Sections
 
 ### 1. Product Overview
-- Product/business name
+- Product name
 - Tagline or one-sentence description
-- Category (e.g., SaaS platform, mobile app, marketplace, service, etc.)
-- Current stage (concept, MVP, beta, launched, scaling, etc.)
+- Category (e.g., SaaS platform, mobile app, marketplace, open source library, internal tool, CLI utility, developer tool, research software, personal project, game, etc.)
+- Product type (commercial, internal, open source, research, personal, etc.) — determines which later sections apply
+- Current stage (concept, MVP, beta, launched, scaling, maintained, etc.)
 
 ### 2. Mission & Vision
 
@@ -64,7 +69,7 @@ You should:
 ### 3. Target Audience
 
 #### Primary Users
-- Who are they? (demographics, roles, characteristics)
+- Who are they? (roles, characteristics, context in which they use the product)
 - What are their key pain points?
 - What are their goals and motivations?
 
@@ -73,7 +78,7 @@ You should:
 - How they differ from primary users
 
 #### Stakeholders
-- Who else is impacted? (buyers, administrators, partners, etc.)
+- Who else is impacted? (buyers, administrators, partners, maintainers, contributors, etc.)
 
 ### 4. Value Proposition
 
@@ -112,18 +117,22 @@ You should:
 
 ### 7. Market & Competition
 
-#### Market Context
-- Market size and opportunity
-- Industry trends driving demand
-- Market maturity
+*Skip or mark "Not Applicable" for internal tools, personal projects, or anything without an external market. Open source projects should adapt this to the ecosystem/alternatives landscape rather than a commercial market.*
+
+#### Market or Ecosystem Context
+- Market size and opportunity (commercial) **or** ecosystem landscape (OSS, research)
+- Trends driving demand or adoption
+- Maturity of the space
 
-#### Competitive Landscape
-- Direct competitors
-- Indirect competitors or alternatives
+#### Competitive Landscape or Alternatives
+- Direct competitors or comparable projects
+- Indirect competitors, alternatives, or incumbent approaches
 - White space or gaps this product fills
 
 ### 8. Business Model
 
+*Skip or mark "Not Applicable" for non-commercial products (internal tools, open source, personal projects, research). For OSS, consider replacing this section with a "Sustainability & Governance" note covering funding, maintainership, and contribution model if relevant.*
+
 #### Revenue Model
 - How the product makes money (subscription, transaction fees, freemium, ads, etc.)
 - Pricing strategy (high-level)
@@ -138,6 +147,8 @@ You should:
 
 ### 9. Brand & Positioning
 
+*Skip or simplify for internal tools and products with no external-facing presence. Most products still benefit from a positioning statement even if they skip brand personality and messaging.*
+
 #### Brand Personality
 - How the brand should feel (professional, friendly, innovative, trustworthy, etc.)
 - Tone and voice characteristics
@@ -151,18 +162,25 @@ You should:
 
 ### 10. Success Metrics
 
-#### Business Metrics
+*Adapt to the product type. Always include user/adoption metrics if meaningful. Include business metrics only for commercial products.*
+
+#### Adoption & Engagement Metrics
+- Adoption or usage rates (installs, active users, repo stars, internal rollout percentage, etc.)
+- Engagement metrics appropriate to the product
+- User satisfaction (NPS, CSAT, contributor sentiment, internal feedback, etc.)
+
+#### Business Metrics *(commercial products only)*
 - Revenue targets
-- User growth goals
+- Paid user growth goals
 - Market share objectives
 
-#### User Metrics
-- Adoption rates
-- Engagement metrics
-- Customer satisfaction (NPS, CSAT, etc.)
+#### Project Health Metrics *(optional, especially for OSS / internal tools)*
+- Contributor count, issue response time, release cadence, uptime, etc.
 
 ### 11. Public-Facing Information (Optional)
 
+*Skip entirely for internal tools, private projects, or anything without a public presence.*
+
 #### Website Copy Elements
 - Homepage headline and subheadline
 - About us summary
@@ -184,11 +202,11 @@ You should:
 - What's being built now
 - Immediate priorities
 
-#### Near-Term (3-6 months)
+#### Near-Term (Next)
 - Planned enhancements
 - Next major milestones
 
-#### Long-Term Vision (1-2 years)
+#### Long-Term Vision (Later)
 - Future capabilities
 - Strategic direction
 
@@ -199,9 +217,11 @@ You should:
 - Dependencies on external factors
 
 #### Risks
-- Market risks
-- Competitive risks
 - Adoption risks
+- Market or competitive risks *(commercial products)*
+- Ecosystem or dependency risks *(OSS, research)*
+- Sustainability or maintainership risks *(OSS, internal tools)*
+- Execution or technical risks
 
 #### Mitigation Strategies
 - How to address key risks
@@ -210,13 +230,13 @@ You should:
 
 ## Tone & Style
 
-- Clear, compelling, business-focused
-- Strategic and visionary
+- Clear, compelling, purpose-focused
+- Strategic and forward-looking
 - Accessible to non-technical audiences
-- Designed for both internal alignment and external communication
+- Designed for alignment among whoever the product's audience is (team, contributors, stakeholders, users, public)
 
 ---
 
-## Input Product/Business Description
+## Input Product Description
 
 $ARGUMENTS

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-research
-description: Research competitors from the product profile and produce a competitive analysis with feature gap identification
+description: Research competitors named in gspec/profile.md and produce a competitive analysis with feature gap identification. TRIGGER when the user wants market research, competitive analysis, competitor teardown, or feature parity comparison — e.g. "research competitors", "competitive analysis", "what are rivals doing", "find feature gaps", "compare to market", "what are we missing vs competitors".
 ---
 
 You are a Senior Product Strategist and Competitive Intelligence Analyst at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-stack
-description: Define the technology stack, frameworks, infrastructure, and architectural patterns
+description: Define or update the technology stack (gspec/stack.md) — frameworks, libraries, databases, hosting, CI/CD, and infrastructure. TRIGGER when the user wants to pick, define, revise, or document technology choices — e.g. "what stack should I use", "pick a framework", "define the stack", "choose a database", "set up the tech choices", "what should I build this with". Prefer this skill over suggesting ad-hoc tech picks.
 ---
 
 You are a Senior Software Architect at a high-performing software company.

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-style
-description: Generate a visual style guide with design tokens, color palette, and component patterns
+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/codex/gspec-analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-analyze
-description: Analyze gspec specs for discrepancies and reconcile conflicts between documents
+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.
@@ -9,6 +9,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
@@ -28,11 +30,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.
 
@@ -58,8 +61,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`
@@ -128,7 +133,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/codex/gspec-architect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gspec-architect
-description: Define the technical architecture project structure, data model, API design, and environment setup
+description: Define or update the technical architecture (gspec/architecture.md) — project structure, data model, API design, component hierarchy, and environment/config. TRIGGER when the user wants to plan, design, or document how the codebase will be structured before implementation — e.g. "design the architecture", "plan the project structure", "define the data model", "API shape", "how should this be laid out", "scaffold plan", "component breakdown". Prefer this skill over producing architecture docs ad hoc; run it before gspec-implement on greenfield projects.
 ---
 
 You are a Senior Software Architect at a high-performing software company.