gspec 1.15.0 → 1.17.0

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

@@ -3,9 +3,11 @@ name: gspec-profile
 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-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/claude/gspec-tasks/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: gspec-tasks
+description: Decompose a feature PRD in gspec/features/ into an ordered, dependency-aware task plan with parallel-execution markers, written to gspec/features/<feature>.tasks.md. TRIGGER when the user wants to plan execution order, break a feature into tasks, identify what can run in parallel, sequence implementation work, or produce a build plan from a PRD — e.g. "break this feature into tasks", "what order should I build this in", "plan the implementation order", "make a task list for X", "what can run in parallel", "decompose feature Y", "ordered task plan". Run this AFTER gspec-feature and BEFORE gspec-implement when a feature is large or has non-obvious ordering. Prefer this skill over ad-hoc task lists.
+---
+
+You are a Senior Engineering Lead at a high-performing software company.
+
+Your task is to take a **feature PRD** from `gspec/features/` and decompose it into an **ordered, dependency-aware task plan** with parallel-execution markers. The output is a separate sibling file at `gspec/features/<feature>.tasks.md` that `gspec-implement` consumes during its planning phase.
+
+The PRD answers *what* and *why*. The tasks file answers *how* and *in what order*.
+
+## When to Run This Skill
+
+Run after `gspec-feature` and before `gspec-implement` when:
+
+- The feature is large enough that build order matters (more than 3-4 capabilities, or non-trivial cross-capability dependencies)
+- Work could be parallelized and you want that surfaced explicitly
+- You want a reviewable execution plan before code is written
+
+Skip this skill for trivial features — `gspec-implement`'s checkbox-driven planning is sufficient there.
+
+---
+
+## Inputs
+
+- **Required**: a feature PRD at `gspec/features/<feature>.md` (the user names the feature; if ambiguous, ask)
+- **Supporting context** (read but don't quote): `gspec/architecture.md`, `gspec/stack.md`. Use these only to inform task granularity and ordering — never to embed project-specific technology choices into the tasks file
+- **Existing tasks file** (if any) at `gspec/features/<feature>.tasks.md` — if present and non-empty, treat it as authoritative state and refuse to overwrite without explicit user confirmation
+
+---
+
+## Workflow
+
+### Phase 1: Discovery
+
+1. Read the target feature PRD in full. Extract every capability and its acceptance criteria.
+2. Read `gspec/architecture.md` and `gspec/stack.md` for ordering signals (e.g., schema must exist before API; API before UI).
+3. If a tasks file already exists for this feature, read it. Decide whether the user wants to (a) regenerate from scratch, (b) add tasks for newly added capabilities only, or (c) abort. Ask before proceeding.
+
+### Phase 2: Decompose
+
+For each unchecked PRD capability:
+
+1. Propose **1–N tasks** that, taken together, satisfy the capability's acceptance criteria.
+2. Tasks should be small enough that a single implementation pass can complete and verify each one (typically 1-3 files, 1-3 acceptance criteria worth of work).
+3. Carry the capability's priority (`P0`/`P1`/`P2`) onto each task.
+4. Record the **`covers:` line** verbatim — quote the capability text from the PRD so the trace is unambiguous. A single task may cover multiple capabilities; a single capability may be covered by multiple tasks.
+
+### Phase 3: Order & Mark Parallelism
+
+1. Identify dependencies. A task depends on another when:
+   - It writes files the other reads or extends
+   - It uses APIs/types/schemas the other introduces
+   - It tests behavior the other implements
+2. Emit a **topological ordering**: list tasks in an order where every `deps:` reference points strictly backwards.
+3. Mark a task `[P]` (parallel-safe) only when it satisfies **both** conditions:
+   - Its `deps:` are all already complete (i.e., earlier in the list and not currently in flight beside it)
+   - It does not write to the same files as another `[P]`-marked sibling at the same level
+   When in doubt, leave `[P]` off. False parallelism causes more pain than missed parallelism.
+
+### Phase 4: Plan-Mode Confirmation
+
+Enter plan mode and present the proposed tasks file content to the user. Show:
+
+- Total task count and how many `[P]`-marked
+- The full proposed file body
+- Any capabilities you could not decompose (explain why)
+- Any cross-feature dependencies you noticed (the user may want to address them in another feature's tasks file)
+
+Wait for approval. The user may edit individual tasks, change ordering, drop or add `[P]` markers, or split/merge tasks.
+
+### Phase 5: Write
+
+After approval, write `gspec/features/<feature>.tasks.md`. Never overwrite a non-empty existing file without explicit user confirmation in Phase 1.
+
+When writing, preserve any existing `spec-version` frontmatter from the prior tasks file. New files use `spec-version: v1`.
+
+---
+
+## Output Format
+
+The tasks file has YAML frontmatter and a single `## Tasks` section.
+
+```markdown
+---
+spec-version: v1
+feature: <feature-slug>
+---
+
+# Tasks: <Feature Name>
+
+## Tasks
+
+- [ ] **T1** [P] **P0** scaffold the Astro page route at `src/pages/index.astro`
+  - deps: —
+  - covers: "Page displays a clear tagline and one-line value proposition that communicates what gspec does"
+- [ ] **T2** **P0** wire CTA copy-to-clipboard interaction
+  - deps: T1
+  - covers: "Page displays a prominent install CTA with the install command"
+- [ ] **T3** [P] **P1** add the workflow diagram component
+  - deps: T1
+  - covers: "Page explains the gspec workflow in three or fewer steps"
+```
+
+### Field rules
+
+- **ID**: `T<n>`, monotonically increasing from `T1`. IDs are stable — never renumber existing tasks during a regenerate; append new ones with the next free number.
+- **`[P]`**: optional parallel marker. Place between the ID and the priority.
+- **Priority**: `P0`, `P1`, or `P2`, matching the source capability.
+- **Description**: one short imperative sentence. Concrete files or modules where useful, but no implementation code.
+- **`deps:`**: comma-separated task IDs. Use `—` (em dash) when there are no dependencies.
+- **`covers:`**: capability text from the PRD, quoted. For tasks covering multiple capabilities, separate quoted strings with `; `.
+
+### What NOT to write
+
+- ❌ No code blocks or pseudocode — that belongs in the implementation step.
+- ❌ No technology choices not already in `stack.md` or `architecture.md`.
+- ❌ No timeline estimates (hours, days, sprints) — see `gspec-feature` for the same rule.
+- ❌ No tasks for capabilities that are already `- [x]` in the PRD, unless the user explicitly requests re-implementation.
+- ❌ No "review" or "documentation" tasks unless the PRD's acceptance criteria explicitly require them.
+
+---
+
+## Relationship to PRD Checkboxes
+
+The tasks file and the PRD use **separate checkboxes**:
+
+- **Task checkboxes** (`- [ ]` / `- [x]` in the tasks file) track *execution state* — flip when the task is done.
+- **Capability checkboxes** (`- [ ]` / `- [x]` in the PRD) track *delivery state* — only flip when **every** task whose `covers:` references that capability is complete.
+
+`gspec-implement` is responsible for keeping both in sync. This skill only writes the initial unchecked tasks file.
+
+---
+
+## Output Rules
+
+- **Use plan mode** in Phase 4. Never write the tasks file before the user approves.
+- One tasks file per feature. Co-located with the PRD as `gspec/features/<feature>.tasks.md`.
+- Begin each file with the YAML frontmatter shown above.
+- Preserve existing frontmatter and existing task IDs when regenerating — append new tasks rather than renumbering.
+- If you discover the PRD itself is ambiguous (a capability has no clear acceptance criteria), pause and recommend the user run `gspec-feature` to refine the PRD before continuing. Do not invent acceptance criteria.
+
+---
+
+## Tone & Style
+
+- Decisive — pick an ordering and defend it; don't list options.
+- Tight — every task line earns its place.
+- Honest about dependencies — it's better to be slightly conservative on `[P]` than to claim parallelism that doesn't hold.
+
+---
+
+## Input Feature
+
+$ARGUMENTS

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

@@ -1,6 +1,6 @@
 ---
 name: gspec-analyze
-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.
@@ -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,13 @@ 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
+9. `gspec/features/*.tasks.md` — For any feature that has a tasks file, read it alongside the PRD. Tasks files declare a build order and parallelism strategy that must stay consistent with the PRD's capabilities
 
 If fewer than two spec files exist, inform the user that there is nothing to cross-reference and stop.
 
@@ -58,8 +62,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`
@@ -75,6 +81,14 @@ Systematically compare specs against each other. Look for these categories of di
 - Acceptance criteria in a feature PRD contradict architectural decisions
 - Edge cases handled differently across specs
 
+#### Tasks ↔ PRD Conflicts
+For any feature that has a `gspec/features/<feature>.tasks.md` file, validate the tasks file against its PRD:
+- A task's `covers:` line quotes capability text that does not exist in the PRD (orphan task)
+- A PRD capability is not `covers:`-referenced by any task in the tasks file (orphan capability — every unchecked capability must be covered by at least one task)
+- A task's checkbox is `- [x]` but its covered capability is still `- [ ]` in the PRD, or vice versa (state inconsistency)
+- A task's `deps:` references a task ID that does not exist in the file
+- The tasks file's `feature:` frontmatter slug does not match its filename's feature slug
+
 **Do NOT flag:**
 - Minor wording or style differences that don't change meaning
 - Missing information (gaps are for `gspec-architect` to handle)
@@ -128,7 +142,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