gspec 1.0.1 → 1.1.0

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,6 +1,62 @@
-# 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.**
+
+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.
+
+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.
+
+## The Problem
+
+Two things go wrong when building with AI:
+
+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.
+
+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.
+
+## How It Works
+
+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.
+
+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.
+
+### The Workflow
+
+```
+Define → Specify → Build → Iterate
+```
+
+**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 |
+
+**2. Specify What to Build** — Define features and requirements.
+
+| 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 |
+
+**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
 
@@ -18,68 +74,65 @@ The CLI will ask which platform you're installing for:
 | Cursor | `.cursor/commands/` |
 | Antigravity | `.agent/skills/` |
 
-You can also skip the prompt by passing a target directly:
+You can skip the prompt by passing a target directly:
 
 ```bash
+npx gspec --target claude
 npx gspec --target cursor
+npx gspec --target antigravity
 ```
 
-## Commands
+That's it. The commands are immediately available in your AI tool.
 
-| 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 |
+## Output Structure
 
-## Workflow
+All specifications live in a `gspec/` directory at your project root:
 
-### 1. Fundamentals
+```
+project-root/
+└── gspec/
+    ├── 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/
+        ├── user-authentication.md
+        ├── dashboard-analytics.md
+        └── ...
+```
 
-Define the foundation that drives how your entire application is built.
+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.
 
-- **`gspec.profile`** — Define *what* the product is, who it's for, and why it exists
-- **`gspec.style`** — Define the visual design language and design system
-- **`gspec.stack`** — Define the technology choices and architecture
-- **`gspec.practices`** — Define the development standards and engineering practices
+## Key Design Decisions
 
-### 2. Pre-Build
+**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.
 
-Define *what* to build.
+**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.
 
-- **`gspec.epic`** — Break down a large body of work into multiple feature PRDs with dependencies and phasing
-- **`gspec.feature`** — Define individual features and requirements (run once per feature)
+**Role-based commands.** Each command adopts a specific professional perspective — product manager, architect, designer, engineer. This ensures specifications are comprehensive and consider multiple viewpoints.
 
-### 3. Build
+**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.
 
-- **`gspec.implement`** — Implement the software using all generated gspec documents
+**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.
 
-### 4. Iterate
+**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.
 
-- **`gspec.dor`** — Make code changes and update gspec specs to keep documentation in sync
-- **`gspec.record`** — Record decisions, changes, or context to gspec specs without touching code
+## Supported Platforms
 
-> Each command is self-contained and will ask clarifying questions when essential information is missing.
+| 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 |
 
-## Output Structure
+## Project Status
 
-```
-project-root/
-└── gspec/
-    ├── profile.md
-    ├── style.md
-    ├── stack.md
-    ├── practices.md
-    ├── epics/
-    │   └── onboarding-flow.md
-    └── features/
-        ├── user-authentication.md
-        ├── dashboard-analytics.md
-        └── ...
-```
+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;
+      }
     }
   }
 
@@ -204,10 +211,92 @@ async function install(targetName, cwd) {
   console.log(chalk.bold(`\n${count} skills installed to ${target.installDir}/\n`));
 }
 
+const MIGRATE_COMMANDS = {
+  claude: '/gspec-migrate',
+  cursor: '/gspec-migrate',
+  antigravity: '/gspec-migrate',
+};
+
+function parseGspecVersion(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  const versionMatch = match[1].match(/^gspec-version:\s*(.+)$/m);
+  return versionMatch ? versionMatch[1].trim() : null;
+}
+
+async function collectGspecFiles(gspecDir) {
+  const files = [];
+
+  const topEntries = await readdir(gspecDir);
+  for (const entry of topEntries) {
+    if (entry.endsWith('.md')) {
+      files.push({ path: join(gspecDir, entry), label: `gspec/${entry}` });
+    }
+  }
+
+  for (const subdir of ['features', 'epics']) {
+    try {
+      const entries = await readdir(join(gspecDir, subdir));
+      for (const entry of entries) {
+        if (entry.endsWith('.md')) {
+          files.push({ path: join(gspecDir, subdir, entry), label: `gspec/${subdir}/${entry}` });
+        }
+      }
+    } catch (e) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+
+  return files;
+}
+
+async function checkGspecFiles(cwd, targetName) {
+  const gspecDir = join(cwd, 'gspec');
+
+  try {
+    await stat(gspecDir);
+  } catch (e) {
+    if (e.code === 'ENOENT') return;
+    throw e;
+  }
+
+  const files = await collectGspecFiles(gspecDir);
+  if (files.length === 0) return;
+
+  const outdated = [];
+  for (const file of files) {
+    const content = await readFile(file.path, 'utf-8');
+    const version = parseGspecVersion(content);
+    if (version === pkg.version) continue;
+    outdated.push({
+      label: file.label,
+      version,
+    });
+  }
+
+  if (outdated.length === 0) return;
+
+  console.log(chalk.yellow(`  Found existing gspec files that may need updating:\n`));
+  for (const file of outdated) {
+    const status = file.version
+      ? `version ${file.version} (current: ${pkg.version})`
+      : `no version (pre-${pkg.version})`;
+    console.log(`    ${chalk.yellow('!')} ${file.label} — ${status}`);
+  }
+  console.log();
+
+  const confirmed = await promptConfirm(chalk.bold('  Update existing gspec files to the current format? [y/N]: '));
+  if (!confirmed) return;
+
+  const cmd = MIGRATE_COMMANDS[targetName] || '/gspec-migrate';
+  console.log(chalk.bold(`\n  To update your files, run the following command in ${TARGETS[targetName].label}:\n`));
+  console.log(`    ${chalk.cyan(cmd)}\n`);
+}
+
 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);
@@ -219,6 +308,7 @@ program
     }
 
     await install(targetName, process.cwd());
+    await checkGspecFiles(process.cwd(), targetName);
   });
 
 program.parse();