gspec 1.0.0 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Baller Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,76 +1,100 @@
-# gspec Commands
+# gspec
 
-This directory contains slash commands for generating project specification documents. Each command produces a standalone Markdown document in the `gspec/` folder.
+**Structured product specifications for AI-assisted development.**
 
-## Installation
+AI coding tools are powerful, but they build better software when they understand *what* you're building and *why*. gspec gives your AI tools that context — a set of living specification documents that define your product, guide implementation, and stay in sync as your project evolves.
 
-Install gspec commands into your project using `npx`. Run from your project root:
+Without structured context, AI tools guess. They make assumptions about your audience, your tech stack, your design language, and your quality standards. gspec eliminates that guesswork by creating a shared specification layer that any AI coding tool can read and follow.
 
-### Claude Code (default)
+## The Problem
 
-```bash
-npx gspec
-```
+Two things go wrong when building with AI:
 
-Installs skills to `.claude/skills/` in your project directory.
+1. **AI tools lack product context.** They don't know your target audience, your design system, your architectural decisions, or your engineering standards. Every prompt starts from zero.
+2. **Specs drift from reality.** Even when you write great specs upfront, they fall out of sync as the project evolves — leading to inconsistency, rework, and compounding confusion.
 
-### Cursor
+gspec solves both problems. It provides a structured specification workflow that gives AI tools rich context, and keeps that context accurate as your codebase changes.
 
-```bash
-npx gspec --target cursor
-```
+## How It Works
 
-Installs commands to `.cursor/commands/` in your project directory.
+gspec installs as a set of slash commands (skills) in your AI coding tool. Each command plays a specific role — business strategist, product manager, architect, designer, engineer — and produces a structured Markdown document in your project's `gspec/` directory.
 
-### Antigravity
+These documents become the shared context for all subsequent AI interactions. When you implement features, your AI reads the specs. When the code changes, the specs update to match.
 
-```bash
-npx gspec --target antigravity
+### The Workflow
+
+```
+Define → Specify → Build → Iterate
 ```
 
-Installs skills to `.agent/skills/` in your project directory.
+**1. Define the Fundamentals** — Establish the foundation that drives every decision.
+
+| Command | Role | What it produces |
+|---|---|---|
+| `gspec.profile` | Business Strategist | Product identity, audience, value proposition, positioning |
+| `gspec.style` | UI/UX Designer | Visual design language, design tokens, component patterns |
+| `gspec.stack` | Software Architect | Technology stack, frameworks, infrastructure, architecture |
+| `gspec.practices` | Engineering Lead | Development standards, code quality, testing, workflows |
 
-## Commands
+**2. Specify What to Build** — Define features and requirements.
 
-| Command | Role | Output | Description |
-|---|---|---|---|
-| `gspec.profile` | Business Strategist | `gspec/profile.md` | Product identity, audience, value proposition, and positioning |
-| `gspec.feature` | Product Manager | `gspec/features/<name>.md` | Product Requirements Document (PRD) for a specific feature |
-| `gspec.epic` | Product Manager | `gspec/epics/<name>.md` + `gspec/features/*.md` | Breaks down a large epic into multiple focused feature PRDs with dependency mapping and phasing |
-| `gspec.style` | UI/UX Designer | `gspec/style.md` | Visual style guide, design tokens, and component patterns |
-| `gspec.stack` | Software Architect | `gspec/stack.md` | Technology stack, frameworks, infrastructure, and tooling |
-| `gspec.practices` | Engineering Lead | `gspec/practices.md` | Development practices, code quality standards, and workflows |
-| `gspec.implement` | Senior Engineer / Tech Lead | Code files | Reads gspec docs, identifies gaps, plans and builds the software |
-| `gspec.dor` | Engineer + Doc Lead | Code files + `gspec/*.md` | Makes code changes and updates gspec specs to keep documentation in sync |
-| `gspec.record` | Doc Lead | `gspec/*.md` | Updates gspec specs to reflect changes, decisions, or context — no code changes |
+| Command | Role | What it produces |
+|---|---|---|
+| `gspec.feature` | Product Manager | PRD for a single feature with prioritized capabilities |
+| `gspec.epic` | Product Manager | Breaks a large epic into multiple feature PRDs with dependency mapping |
 
-## Recommended Order of Operations
+**3. Build** — Implement with full context.
+
+| Command | Role | What it does |
+|---|---|---|
+| `gspec.implement` | Senior Engineer | Reads all specs, identifies gaps, researches competitors, plans and builds |
+
+**4. Iterate** — Keep specs and code in sync as the project evolves.
+
+| Command | Role | What it does |
+|---|---|---|
+| `gspec.dor` | Engineer + Doc Lead | Makes code changes and updates specs to match |
+| `gspec.record` | Doc Lead | Updates specs to reflect decisions or changes — no code modifications |
+
+Each command is self-contained and will ask clarifying questions when essential information is missing.
+
+## Installation
+
+Run from your project root:
+
+```bash
+npx gspec
+```
 
-Run the commands in this order for the best results:
+The CLI will ask which platform you're installing for:
 
-1. **`gspec.profile`** — Define *what* the product is, who it's for, and why it exists
-2. **`gspec.feature`** — Define individual features and requirements (run once per feature)
-3. **`gspec.epic`** — Break down a large body of work into multiple feature PRDs with dependencies and phasing
-4. **`gspec.style`** — Define the visual design language and design system
-5. **`gspec.stack`** — Define the technology choices and architecture
-6. **`gspec.practices`** — Define the development standards and engineering practices
-7. **`gspec.implement`** — Implement the software using all generated gspec documents
-8. **`gspec.dor`** — Iterate on the codebase and keep gspec specs up to date with changes
-9. **`gspec.record`** — Record decisions, changes, or context to gspec specs without touching code
+| Platform | Install path |
+|---|---|
+| Claude Code | `.claude/skills/` |
+| Cursor | `.cursor/commands/` |
+| Antigravity | `.agent/skills/` |
 
-> Each command is self-contained and will ask clarifying questions when essential information is missing.
->
-> After initial implementation, use `gspec.dor` for ongoing changes. It makes code changes and updates the relevant spec files to keep everything in sync.
+You can skip the prompt by passing a target directly:
+
+```bash
+npx gspec --target claude
+npx gspec --target cursor
+npx gspec --target antigravity
+```
+
+That's it. The commands are immediately available in your AI tool.
 
 ## Output Structure
 
+All specifications live in a `gspec/` directory at your project root:
+
 ```
 project-root/
 └── gspec/
-    ├── profile.md
-    ├── style.md
-    ├── stack.md
-    ├── practices.md
+    ├── profile.md          # Product identity and positioning
+    ├── style.md            # Visual design language
+    ├── stack.md            # Technology stack and architecture
+    ├── practices.md        # Development standards
     ├── epics/
     │   └── onboarding-flow.md
     └── features/
@@ -78,3 +102,37 @@ project-root/
         ├── dashboard-analytics.md
         └── ...
 ```
+
+These are standard Markdown files. They live in your repo, are version-controlled with your code, and are readable by both humans and AI tools.
+
+## Key Design Decisions
+
+**Spec-first development.** Every implementation decision traces back to a specification. AI tools don't guess — they follow documented decisions about your product, stack, design, and standards.
+
+**Living documents.** Specifications aren't write-once artifacts. The `dor` and `record` commands keep them in sync as your project evolves, so they remain a reliable source of truth.
+
+**Role-based commands.** Each command adopts a specific professional perspective — product manager, architect, designer, engineer. This ensures specifications are comprehensive and consider multiple viewpoints.
+
+**Incremental implementation.** Feature PRDs use checkboxes to track which capabilities have been built. The `implement` command reads these to know what's done and what's remaining, so it can be run multiple times as your project grows.
+
+**Competitive research.** The `implement` command can optionally research competitors named in your product profile, identifying table-stakes features you might be missing and opportunities for differentiation.
+
+**Platform-agnostic.** A single set of source commands builds for Claude Code, Cursor, and Antigravity. The build system handles platform-specific formatting so the commands stay consistent across tools.
+
+## Supported Platforms
+
+| Platform | Version | Status |
+|---|---|---|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Skills format | Supported |
+| [Cursor](https://www.cursor.com/) | Commands format | Supported |
+| [Antigravity](https://www.antigravity.dev/) | Skills format | Supported |
+
+## Project Status
+
+gspec is early-stage and actively evolving. The core workflow is stable, but commands and output formats may change as AI tool capabilities expand and user feedback comes in.
+
+If you run into issues or have ideas, please [open an issue](https://github.com/gballer77/gspec/issues).
+
+## License
+
+[MIT](LICENSE)

package/bin/gspec.js

@@ -9,19 +9,21 @@ import chalk from 'chalk';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DIST_DIR = join(__dirname, '..', 'dist');
+const pkg = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
 
 const BANNER = `
-  ${chalk.cyan('╔══════════════════════════════════════════╗')}
-  ${chalk.cyan('║')}                                          ${chalk.cyan('║')}
-  ${chalk.cyan('║')}   ${chalk.bold.white(' ██████  ███████ ██████  ███████  ██████')}  ${chalk.cyan('║')}
-  ${chalk.cyan('║')}   ${chalk.bold.white('██       ██      ██   ██ ██      ██      ')} ${chalk.cyan('║')}
-  ${chalk.cyan('║')}   ${chalk.bold.white('██   ███ ███████ ██████  █████   ██      ')} ${chalk.cyan('║')}
-  ${chalk.cyan('║')}   ${chalk.bold.white('██    ██      ██ ██      ██      ██      ')} ${chalk.cyan('║')}
-  ${chalk.cyan('║')}   ${chalk.bold.white(' ██████  ███████ ██      ███████  ██████')}  ${chalk.cyan('║')}
-  ${chalk.cyan('║')}                                          ${chalk.cyan('║')}
-  ${chalk.cyan('║')}   ${chalk.dim('AI-powered project specification tools')}   ${chalk.cyan('║')}
-  ${chalk.cyan('║')}                                          ${chalk.cyan('║')}
-  ${chalk.cyan('╚══════════════════════════════════════════╝')}
+  ${chalk.cyan('╔══════════════════════════════════════════════╗')}
+  ${chalk.cyan('║')}                                              ${chalk.cyan('║')}
+  ${chalk.cyan('║')}   ${chalk.bold.white(' ██████  ███████ ██████  ███████  ██████')}   ${chalk.cyan('║')}
+  ${chalk.cyan('║')}   ${chalk.bold.white('██       ██      ██   ██ ██      ██      ')}  ${chalk.cyan('║')}
+  ${chalk.cyan('║')}   ${chalk.bold.white('██   ███ ███████ ██████  █████   ██      ')}  ${chalk.cyan('║')}
+  ${chalk.cyan('║')}   ${chalk.bold.white('██    ██      ██ ██      ██      ██      ')}  ${chalk.cyan('║')}
+  ${chalk.cyan('║')}   ${chalk.bold.white(' ██████  ███████ ██      ███████  ██████')}   ${chalk.cyan('║')}
+  ${chalk.cyan('║')}                                              ${chalk.cyan('║')}
+  ${chalk.cyan('║')}    ${chalk.dim('AI-powered project specification tools')}    ${chalk.cyan('║')}
+  ${chalk.cyan('║')}                                              ${chalk.cyan('║')}
+  ${chalk.cyan('╚══════════════════════════════════════════════╝')}
+  ${chalk.white('═════════════════════════════baller.software═══')}
 `;
 
 const TARGETS = {
@@ -96,8 +98,9 @@ async function findExistingFiles(target, cwd) {
 
   try {
     await stat(destBase);
-  } catch {
-    return existing;
+  } catch (e) {
+    if (e.code === 'ENOENT') return existing;
+    throw e;
   }
 
   if (target.layout === 'flat') {
@@ -106,7 +109,9 @@ async function findExistingFiles(target, cwd) {
       try {
         await stat(join(destBase, file));
         existing.push(file);
-      } catch { /* doesn't exist */ }
+      } catch (e) {
+        if (e.code !== 'ENOENT') throw e;
+      }
     }
   } else {
     const srcEntries = await readdir(target.sourceDir);
@@ -116,7 +121,9 @@ async function findExistingFiles(target, cwd) {
       try {
         await stat(join(destBase, entry, 'SKILL.md'));
         existing.push(`${entry}/SKILL.md`);
-      } catch { /* doesn't exist */ }
+      } catch (e) {
+        if (e.code !== 'ENOENT') throw e;
+      }
     }
   }
 
@@ -207,7 +214,7 @@ async function install(targetName, cwd) {
 program
   .name('gspec')
   .description('Install gspec specification commands')
-  .version('1.0.0')
+  .version(pkg.version)
   .option('-t, --target <target>', 'target platform (claude, cursor, antigravity)')
   .action(async (opts) => {
     console.log(BANNER);

package/commands/gspec.dor.md

@@ -58,6 +58,17 @@ Execute the code changes:
 5. **Surface new issues as they arise** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 6. **Track spec implications as you work** — As you implement, mentally note which gspec documents will need updating based on what you are changing
 
+### Phase 3.5: Validate — Ensure Tests Pass
+
+Before updating any specs, verify the code changes are sound:
+
+1. **Check for existing tests** — Look for a test suite, test runner configuration, or test scripts in `package.json`, `Makefile`, or equivalent
+2. **If tests exist, run them** — Execute the project's test suite and confirm all tests pass
+3. **If tests fail** — Fix the failing tests before proceeding. Do not move to spec updates with a broken test suite
+4. **If no tests exist** — Note this and proceed. Do not create a test suite unless the user requests one or `gspec/practices.md` requires it
+
+This gate ensures specs are only updated to reflect working, validated code — never broken implementations.
+
 ### Phase 4: Assess — Determine Spec Impact
 
 After code changes are complete, systematically evaluate which gspec documents need updating. Apply this decision matrix:
@@ -70,7 +81,8 @@ After code changes are complete, systematically evaluate which gspec documents n
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -150,6 +162,8 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment. For small, obvious changes, no annotation may be needed. For significant scope changes, a parenthetical note aids understanding.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **Implementation checkboxes.** Feature PRDs use markdown checkboxes (`- [ ]` / `- [x]`) on capabilities to track implementation status for `gspec-implement`. When DOR adds new capabilities, use unchecked checkboxes (`- [ ]`). When modifying a capability that was already checked (`- [x]`) and the code change reflects the modification, keep it checked. When creating a new feature PRD, use unchecked checkboxes for all capabilities. Do not check off capabilities that DOR did not implement in the current session.

package/commands/gspec.record.md

@@ -65,7 +65,8 @@ Systematically evaluate which gspec documents need updating. Apply this decision
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -143,6 +144,8 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **No code changes.** This command never creates, modifies, or deletes code files. If the user needs code changes alongside spec updates, suggest using `gspec-dor` instead.

package/dist/antigravity/gspec-dor/SKILL.md

@@ -63,6 +63,17 @@ Execute the code changes:
 5. **Surface new issues as they arise** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 6. **Track spec implications as you work** — As you implement, mentally note which gspec documents will need updating based on what you are changing
 
+### Phase 3.5: Validate — Ensure Tests Pass
+
+Before updating any specs, verify the code changes are sound:
+
+1. **Check for existing tests** — Look for a test suite, test runner configuration, or test scripts in `package.json`, `Makefile`, or equivalent
+2. **If tests exist, run them** — Execute the project's test suite and confirm all tests pass
+3. **If tests fail** — Fix the failing tests before proceeding. Do not move to spec updates with a broken test suite
+4. **If no tests exist** — Note this and proceed. Do not create a test suite unless the user requests one or `gspec/practices.md` requires it
+
+This gate ensures specs are only updated to reflect working, validated code — never broken implementations.
+
 ### Phase 4: Assess — Determine Spec Impact
 
 After code changes are complete, systematically evaluate which gspec documents need updating. Apply this decision matrix:
@@ -75,7 +86,8 @@ After code changes are complete, systematically evaluate which gspec documents n
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -155,6 +167,8 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment. For small, obvious changes, no annotation may be needed. For significant scope changes, a parenthetical note aids understanding.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **Implementation checkboxes.** Feature PRDs use markdown checkboxes (`- [ ]` / `- [x]`) on capabilities to track implementation status for `gspec-implement`. When DOR adds new capabilities, use unchecked checkboxes (`- [ ]`). When modifying a capability that was already checked (`- [x]`) and the code change reflects the modification, keep it checked. When creating a new feature PRD, use unchecked checkboxes for all capabilities. Do not check off capabilities that DOR did not implement in the current session.

package/dist/antigravity/gspec-record/SKILL.md

@@ -70,7 +70,8 @@ Systematically evaluate which gspec documents need updating. Apply this decision
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -148,6 +149,8 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **No code changes.** This command never creates, modifies, or deletes code files. If the user needs code changes alongside spec updates, suggest using `gspec-dor` instead.

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

@@ -63,6 +63,17 @@ Execute the code changes:
 5. **Surface new issues as they arise** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 6. **Track spec implications as you work** — As you implement, mentally note which gspec documents will need updating based on what you are changing
 
+### Phase 3.5: Validate — Ensure Tests Pass
+
+Before updating any specs, verify the code changes are sound:
+
+1. **Check for existing tests** — Look for a test suite, test runner configuration, or test scripts in `package.json`, `Makefile`, or equivalent
+2. **If tests exist, run them** — Execute the project's test suite and confirm all tests pass
+3. **If tests fail** — Fix the failing tests before proceeding. Do not move to spec updates with a broken test suite
+4. **If no tests exist** — Note this and proceed. Do not create a test suite unless the user requests one or `gspec/practices.md` requires it
+
+This gate ensures specs are only updated to reflect working, validated code — never broken implementations.
+
 ### Phase 4: Assess — Determine Spec Impact
 
 After code changes are complete, systematically evaluate which gspec documents need updating. Apply this decision matrix:
@@ -75,7 +86,8 @@ After code changes are complete, systematically evaluate which gspec documents n
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -155,6 +167,8 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment. For small, obvious changes, no annotation may be needed. For significant scope changes, a parenthetical note aids understanding.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **Implementation checkboxes.** Feature PRDs use markdown checkboxes (`- [ ]` / `- [x]`) on capabilities to track implementation status for `gspec-implement`. When DOR adds new capabilities, use unchecked checkboxes (`- [ ]`). When modifying a capability that was already checked (`- [x]`) and the code change reflects the modification, keep it checked. When creating a new feature PRD, use unchecked checkboxes for all capabilities. Do not check off capabilities that DOR did not implement in the current session.

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

@@ -70,7 +70,8 @@ Systematically evaluate which gspec documents need updating. Apply this decision
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -148,6 +149,8 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **No code changes.** This command never creates, modifies, or deletes code files. If the user needs code changes alongside spec updates, suggest using `gspec-dor` instead.

package/dist/cursor/gspec-dor.mdc

@@ -62,6 +62,17 @@ Execute the code changes:
 5. **Surface new issues as they arise** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 6. **Track spec implications as you work** — As you implement, mentally note which gspec documents will need updating based on what you are changing
 
+### Phase 3.5: Validate — Ensure Tests Pass
+
+Before updating any specs, verify the code changes are sound:
+
+1. **Check for existing tests** — Look for a test suite, test runner configuration, or test scripts in `package.json`, `Makefile`, or equivalent
+2. **If tests exist, run them** — Execute the project's test suite and confirm all tests pass
+3. **If tests fail** — Fix the failing tests before proceeding. Do not move to spec updates with a broken test suite
+4. **If no tests exist** — Note this and proceed. Do not create a test suite unless the user requests one or `gspec/practices.md` requires it
+
+This gate ensures specs are only updated to reflect working, validated code — never broken implementations.
+
 ### Phase 4: Assess — Determine Spec Impact
 
 After code changes are complete, systematically evaluate which gspec documents need updating. Apply this decision matrix:
@@ -74,7 +85,8 @@ After code changes are complete, systematically evaluate which gspec documents n
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -154,6 +166,8 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment. For small, obvious changes, no annotation may be needed. For significant scope changes, a parenthetical note aids understanding.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **Implementation checkboxes.** Feature PRDs use markdown checkboxes (`- [ ]` / `- [x]`) on capabilities to track implementation status for `gspec-implement`. When DOR adds new capabilities, use unchecked checkboxes (`- [ ]`). When modifying a capability that was already checked (`- [x]`) and the code change reflects the modification, keep it checked. When creating a new feature PRD, use unchecked checkboxes for all capabilities. Do not check off capabilities that DOR did not implement in the current session.

package/dist/cursor/gspec-record.mdc

@@ -69,7 +69,8 @@ Systematically evaluate which gspec documents need updating. Apply this decision
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -147,6 +148,8 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **No code changes.** This command never creates, modifies, or deletes code files. If the user needs code changes alongside spec updates, suggest using `gspec-dor` instead.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gspec",
-    "version": "1.0.0",
+    "version": "1.0.3",
     "description": "Install gspec specification commands for Claude Code, Cursor, and other AI tools",
     "main": "bin/gspec.js",
     "type": "module",
@@ -19,8 +19,11 @@
         "build:antigravity": "node scripts/build.js antigravity",
         "prepublishOnly": "npm run build"
     },
-    "author": "",
-    "license": "ISC",
+    "author": "Baller Software",
+    "repository": {
+        "url": "https://github.com/gballer77/gspec"
+    },
+    "license": "MIT",
     "dependencies": {
         "chalk": "^5.6.2",
         "commander": "^11.1.0"