gspec 1.7.0 → 1.10.0

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

@@ -27,7 +27,7 @@ You should:
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -115,34 +115,27 @@ You should:
 - Component color adjustments
 - Contrast considerations
 
-#### Theme Switching
-- How themes interact with the color palette
-- Token mapping between themes
+### 6. Component Styling
 
-### 6. Components
+> **Focus on visual styling only** — colors, borders, typography, spacing, and state appearances. Do NOT define component structure, layout behavior, or interaction patterns (those belong in feature PRDs). The goal is to answer "what does it look like?" not "how does it work?"
 
 #### Buttons
-- Primary, secondary, tertiary styles
-- States (default, hover, active, disabled)
-- Sizes and padding
-- Border radius
+- Color treatments for primary, secondary, ghost variants
+- States: default, hover, active, disabled appearances
+- Sizes and border radius
 
 #### Form Elements
-- Input fields
-- Dropdowns, checkboxes, radio buttons
-- Labels and helper text
-- Validation states
+- Input field colors, borders, and focus ring styles
+- Label and helper text typography
+- Validation state colors (error, success)
 
 #### Cards & Containers
-- Background colors
-- Border styles
-- Shadow elevations
-- Corner radius
+- Background colors and border styles
+- Shadow elevations and corner radius
 
-#### Navigation
-- Header/navbar styles
-- Menu patterns
-- Active states
+#### Navigation Elements
+- Link colors: default, hover, active states
+- Background treatments for navigation surfaces
 
 ### 7. Visual Effects
 
@@ -162,11 +155,13 @@ You should:
 
 ### 8. Iconography
 
-#### Icon Style
-- Outlined vs filled
+> **The style guide is the single authority for icon library choices.** The stack document defines the CSS framework and component library (e.g., shadcn/ui); the style guide defines which icon set is used. This separation ensures icon decisions are driven by design rationale (visual consistency, stroke style) while component library decisions remain with the technology stack (framework compatibility).
+
+#### Icon Library
+- Specific icon library recommendation with rationale
+- Outlined vs filled style
 - Stroke width
 - Size standards
-- Icon library recommendation
 
 #### Usage Guidelines
 - When to use icons

package/dist/cursor/gspec-analyze.mdc

@@ -27,7 +27,7 @@ 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 patterns
+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

package/dist/cursor/gspec-architect.mdc

@@ -44,7 +44,7 @@ All of these provide essential context. If any are missing, note the gap and mak
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/cursor/gspec-feature.mdc

@@ -84,7 +84,7 @@ Feature PRDs are designed to be **portable across projects**. A feature spec wri
 - Begin each file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/cursor/gspec-implement.mdc

@@ -104,11 +104,11 @@ Present a brief scaffold summary to the user before proceeding to feature implem
 
 1. **Announce the phase** — State which phase you're starting, what it covers, and what capabilities will be implemented
 2. **Implement the phase:**
-   a. **Follow the stack** — Use the exact technologies, frameworks, and patterns defined in `gspec/stack.md`
-   b. **Follow the practices** — Adhere to coding standards, testing requirements, and conventions from `gspec/practices.md`
-   c. **Follow the style** — Apply the design system, tokens, and component patterns from `gspec/style.md`
+   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
-3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `gspec-version` YAML frontmatter. If a file lacks frontmatter, add `---\ngspec-version: 1.7.0\n---` at the top.
+3. **Mark capabilities as implemented** — After successfully implementing each capability, immediately update the feature PRD by changing its checkbox from `- [ ]` to `- [x]`. Do this incrementally as each capability is completed, not in a batch at the end. If a capability line did not have a checkbox prefix, add one as `- [x]`. This ensures that if the session is interrupted, progress is not lost. When updating gspec files, preserve existing `gspec-version` YAML frontmatter. If a file lacks frontmatter, add `---\ngspec-version: 1.10.0\n---` at the top.
 4. **Run tests** — Execute the tests defined for this phase (and any existing tests to catch regressions). Fix any failures before proceeding.
 6. **Surface new gaps** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 7. **Pause and report** — After completing the phase and confirming tests pass, present a phase completion summary to the user:

package/dist/cursor/gspec-migrate.mdc

@@ -4,7 +4,7 @@ description: Migrate existing gspec files to the current format when upgrading t
 
 You are a Technical Documentation Migration Specialist.
 
-Your task is to update existing gspec specification documents to match the current gspec format (version 1.7.0). You preserve all substantive content while ensuring documents follow the latest structural conventions.
+Your task is to update existing gspec specification documents to match the current gspec format (version 1.10.0). You preserve all substantive content while ensuring documents follow the latest structural conventions.
 
 ---
 
@@ -20,14 +20,14 @@ Scan the `gspec/` directory for all Markdown files:
 For each file, check the YAML frontmatter at the top of the file:
 - If the file starts with `---` followed by YAML content and another `---`, read the `gspec-version` field
 - If no frontmatter exists, the file predates version tracking
-- If `gspec-version` matches `1.7.0`, the file is current — skip it
+- If `gspec-version` matches `1.10.0`, the file is current — skip it
 
 Present an inventory to the user:
 
 > **gspec File Inventory:**
 > - `gspec/profile.md` — no version (needs migration)
 > - `gspec/stack.md` — version 1.0.3 (needs migration)
-> - `gspec/style.md` — version 1.7.0 (current, skipping)
+> - `gspec/style.md` — version 1.10.0 (current, skipping)
 > - `gspec/features/user-auth.md` — no version (needs migration)
 
 Ask the user to confirm which files to migrate, or confirm all.
@@ -62,7 +62,7 @@ For each file to migrate:
 5. **Add or update the frontmatter** — Ensure the file starts with:
    ```
    ---
-   gspec-version: 1.7.0
+   gspec-version: 1.10.0
    ---
    ```
 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.
@@ -76,7 +76,7 @@ After migrating all files:
 3. **Present a completion summary**:
 
 > **Migration Complete:**
-> - 4 files migrated to version 1.7.0
+> - 4 files migrated to version 1.10.0
 > - 2 files were already current (skipped)
 > - Content preserved in all files
 > - Sections reorganized: [list any structural changes]

package/dist/cursor/gspec-practices.mdc

@@ -24,7 +24,7 @@ You should:
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -38,8 +38,10 @@ You should:
 - Focus on practices that matter for this specific project
 - Avoid generic advice that doesn't apply
 - **Do NOT include technology stack information** — this is documented separately
-- **Do NOT prescribe specific testing frameworks, tools, or libraries** — focus on testing principles, patterns, and practices, not which tools to use
+- **Do NOT prescribe specific testing frameworks, tools, or libraries** — focus on testing principles, patterns, and practices. The stack document (`gspec/stack.md`) is the single authority for which test tools are used.
+- **DO define CI/CD pipeline structure** — the practices document defines pipeline stages, gates, and ordering (lint → typecheck → test → build → deploy). The stack document defines which CI/CD platform technology is used (GitHub Actions, GitLab CI, etc.).
 - **Mark sections as "Not Applicable"** when they don't apply to this project
+- **Precedence rule**: Where this document conflicts with technology-specific practices in `gspec/stack.md`, the stack's technology-specific practices take precedence for framework-specific concerns (e.g., file naming conventions dictated by a framework). This document governs general engineering principles.
 
 ---
 

package/dist/cursor/gspec-profile.mdc

@@ -24,7 +24,7 @@ You should:
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.

package/dist/cursor/gspec-research.mdc

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

package/dist/cursor/gspec-stack.mdc

@@ -24,7 +24,7 @@ You should:
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -95,6 +95,8 @@ You should:
 - Responsive design tooling
 
 - **Note**: Visual design values (colors, typography, spacing) are documented separately as framework-agnostic design tokens; include here how the chosen CSS framework maps to those tokens
+- **Component library** (if applicable) — e.g., shadcn/ui, Headless UI, Radix UI. Component libraries are framework-specific technology choices and belong in the stack, not the style guide.
+- **Note**: Icon libraries (e.g., HeroIcons, Lucide) are defined in `gspec/style.md`, not here. The stack defines the CSS framework and component library; the style defines the icon set. Do NOT include an iconography section in the stack document.
 
 ### 5. Backend Stack
 **Mark as N/A if this is a frontend-only or static site project**
@@ -133,9 +135,9 @@ You should:
 - Scaling approach
 
 #### CI/CD Pipeline
-- CI/CD platform (GitHub Actions, GitLab CI, Jenkins, etc.)
-- Pipeline stages
-- Deployment automation
+- CI/CD platform technology (GitHub Actions, GitLab CI, Jenkins, etc.) and rationale
+- Deployment automation and trigger configuration
+- **Note**: The stack defines *which CI/CD technology* is used. The pipeline structure (stages, gates, ordering) is defined in `gspec/practices.md`. Include platform-specific configuration details here (e.g., workflow YAML format, runner setup), not pipeline philosophy.
 
 #### Infrastructure as Code
 - IaC tool (Terraform, CloudFormation, Pulumi, etc.)
@@ -193,10 +195,13 @@ You should:
 
 ### 10. Testing Infrastructure
 
+> **The stack is the single authority for test tooling choices.** Define which frameworks and tools are used here. Testing philosophy, patterns, and coverage requirements are defined in `gspec/practices.md`.
+
 #### Testing Frameworks
-- Unit testing framework
+- Unit testing framework (Vitest, Jest, pytest, etc.) and rationale
 - Integration testing tools
-- E2E testing framework (Playwright, Cypress, etc.)
+- E2E testing framework (Playwright, Cypress, etc.) and rationale
+- Component testing tools (if applicable)
 
 #### Test Data Management
 - Test database strategy
@@ -223,7 +228,7 @@ You should:
 ### 12. Development Tools
 
 #### Package Management
-- Package manager (npm, yarn, pnpm, pip, maven, etc.)
+- **Package manager** — Explicitly declare the package manager (npm, yarn, pnpm, pip, maven, etc.) with rationale for the choice. This must be stated clearly so all other gspec commands and CI/CD configuration use the correct tool.
 - Dependency management strategy
 - Private package registry (if applicable)
 

package/dist/cursor/gspec-style.mdc

@@ -26,7 +26,7 @@ You should:
 - Begin the file with YAML frontmatter containing the gspec version:
   ```
   ---
-  gspec-version: 1.7.0
+  gspec-version: 1.10.0
   ---
   ```
   The frontmatter must be the very first content in the file, before the main heading.
@@ -114,34 +114,27 @@ You should:
 - Component color adjustments
 - Contrast considerations
 
-#### Theme Switching
-- How themes interact with the color palette
-- Token mapping between themes
+### 6. Component Styling
 
-### 6. Components
+> **Focus on visual styling only** — colors, borders, typography, spacing, and state appearances. Do NOT define component structure, layout behavior, or interaction patterns (those belong in feature PRDs). The goal is to answer "what does it look like?" not "how does it work?"
 
 #### Buttons
-- Primary, secondary, tertiary styles
-- States (default, hover, active, disabled)
-- Sizes and padding
-- Border radius
+- Color treatments for primary, secondary, ghost variants
+- States: default, hover, active, disabled appearances
+- Sizes and border radius
 
 #### Form Elements
-- Input fields
-- Dropdowns, checkboxes, radio buttons
-- Labels and helper text
-- Validation states
+- Input field colors, borders, and focus ring styles
+- Label and helper text typography
+- Validation state colors (error, success)
 
 #### Cards & Containers
-- Background colors
-- Border styles
-- Shadow elevations
-- Corner radius
+- Background colors and border styles
+- Shadow elevations and corner radius
 
-#### Navigation
-- Header/navbar styles
-- Menu patterns
-- Active states
+#### Navigation Elements
+- Link colors: default, hover, active states
+- Background treatments for navigation surfaces
 
 ### 7. Visual Effects
 
@@ -161,11 +154,13 @@ You should:
 
 ### 8. Iconography
 
-#### Icon Style
-- Outlined vs filled
+> **The style guide is the single authority for icon library choices.** The stack document defines the CSS framework and component library (e.g., shadcn/ui); the style guide defines which icon set is used. This separation ensures icon decisions are driven by design rationale (visual consistency, stroke style) while component library decisions remain with the technology stack (framework compatibility).
+
+#### Icon Library
+- Specific icon library recommendation with rationale
+- Outlined vs filled style
 - Stroke width
 - Size standards
-- Icon library recommendation
 
 #### Usage Guidelines
 - When to use icons

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

@@ -0,0 +1,168 @@
+---
+name: gspec-analyze
+description: Analyze gspec specs for discrepancies and reconcile conflicts between documents
+---
+
+You are a Specification Analyst at a high-performing software company.
+
+Your task is to read all existing gspec specification documents, identify discrepancies and contradictions between them, and guide the user through reconciling each one. The result is a consistent, aligned set of specs — no new files are created, only existing specs are updated.
+
+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.
+
+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
+- Present each discrepancy to the user one at a time, clearly showing what each spec says and why they conflict
+- Offer 2-3 resolution options with tradeoffs when applicable
+- Wait for the user's decision before moving to the next discrepancy
+- Update the affected spec files to reflect each resolution
+- Never create new markdown files — only update existing ones
+
+---
+
+## 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` — 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
+
+If fewer than two spec files exist, inform the user that there is nothing to cross-reference and stop.
+
+---
+
+### Phase 2: Cross-Reference and Identify Discrepancies
+
+Systematically compare specs against each other. Look for these categories of discrepancy:
+
+#### Technology Conflicts
+- A technology named in `stack.md` differs from what `architecture.md` specifies (e.g., stack says PostgreSQL but architecture references MongoDB)
+- A feature PRD references a library or framework not present in the stack
+- Architecture specifies patterns or conventions that contradict the stack's framework choices
+
+#### Data Model Conflicts
+- A feature PRD describes data fields or entities that conflict with the data model in `architecture.md`
+- Two feature PRDs define the same entity differently
+- Architecture references entities not mentioned in any feature PRD, or vice versa
+
+#### API & Endpoint Conflicts
+- A feature PRD describes an API behavior that conflicts with the API design in `architecture.md`
+- Architecture defines endpoints that don't map to any feature capability
+- 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`
+
+#### Practice & Convention Conflicts
+- Architecture's file naming, testing approach, or code organization contradicts `practices.md`
+- Feature PRDs reference development patterns that conflict with documented practices
+
+#### Scope & Priority Conflicts
+- A feature capability is marked P0 in one place but P1 or P2 in another
+- Profile describes scope or positioning that conflicts with what features actually define
+- Research recommendations conflict with decisions already made in other specs
+
+#### Behavioral Conflicts
+- Two specs describe the same user flow differently
+- Acceptance criteria in a feature PRD contradict architectural decisions
+- Edge cases handled differently across specs
+
+**Do NOT flag:**
+- Minor wording or style differences that don't change meaning
+- Missing information (gaps are for `gspec-architect` to handle)
+- Differences in level of detail (one spec being more detailed than another is expected)
+
+---
+
+### Phase 3: Present Discrepancies for Reconciliation
+
+If no discrepancies are found, tell the user their specs are consistent and stop.
+
+If discrepancies are found:
+
+1. **Summarize** the total number of discrepancies found, grouped by category
+2. **Present each discrepancy one at a time**, in order of severity (most impactful first)
+
+For each discrepancy, present:
+
+```
+### Discrepancy [N]: [Brief title]
+
+**Category:** [Technology / Data Model / API / Design / Practice / Scope / Behavioral]
+
+**What conflicts:**
+- **[File A] says:** [exact quote or precise summary]
+- **[File B] says:** [exact quote or precise summary]
+
+**Why this matters:** [1-2 sentences on what goes wrong if this isn't resolved — e.g., the implementing agent will receive contradictory instructions]
+
+**Options:**
+1. **[Option A]** — [Description]. Update [File X].
+2. **[Option B]** — [Description]. Update [File Y].
+3. **[Option C, if applicable]** — [Description]. Update [both files / different resolution].
+
+Which would you like?
+```
+
+**Wait for the user's response before proceeding.** The user may:
+- Choose an option by number
+- Provide a different resolution
+- Ask for more context
+- Skip the discrepancy (mark it as deferred)
+
+After the user decides, immediately update the affected spec file(s) to reflect the resolution. Then present the next discrepancy.
+
+---
+
+### Phase 4: Apply Resolutions
+
+When updating specs to resolve a discrepancy:
+
+- **Surgical updates only** — change the minimum text needed to resolve the conflict
+- **Preserve format and tone** — match the existing document's style, heading structure, and voice
+- **Preserve `gspec-version` frontmatter** — do not alter or remove it
+- **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
+
+---
+
+### Phase 5: Final Verification
+
+After all discrepancies have been resolved (or deferred):
+
+1. **Re-read the updated specs** to confirm the resolutions didn't introduce new conflicts
+2. **Present a summary:**
+   - Number of discrepancies found
+   - Number resolved
+   - Number deferred (if any), with a note on what remains unresolved
+   - List of files that were updated
+3. If new conflicts were introduced by the resolutions, flag them and guide the user through resolving those as well
+
+---
+
+## Rules
+
+- **Never create new files.** This command only reads and updates existing gspec documents.
+- **Never silently update specs.** Every change requires user approval via the discrepancy resolution flow.
+- **One discrepancy at a time.** Do not batch resolutions — the user decides each one individually.
+- **Be precise about what conflicts.** Quote or closely paraphrase the conflicting text. Do not be vague.
+- **Prioritize by impact.** Present discrepancies that would cause the most confusion during implementation first.
+- **Stay neutral.** Present options fairly. You may recommend a preferred option, but do not presume the user's choice.
+
+---
+
+## Tone & Style
+
+- Precise and analytical — you are cross-referencing documents, not rewriting them
+- Neutral when presenting options — let the user decide, recommend but don't presume
+- Efficient — get to the conflicts quickly, don't over-explain what each spec is for
+- Respectful of existing specs — these are authoritative documents, you are finding where they disagree
+